OpenSocial Social Data Specification 2.0.1opensocial-and-gadgets-spec@googlegroups.comThis document defines all the data objects used in the
OpenSocial APIs. Objects defined here make use of the Core Data objects. The structure of the
data is used by many different APIs:
JavaScript within the gadget is done using osapi APIs,
defined in the Social Gadget
SpecificationREST and RPC access is done using APIs defined in the
Social API Server SpecDomain name examples use RFC2606.The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
RFC2119.An implementation is not compliant if it fails to satisfy one or more of
the MUST or REQUIRED level requirements for the protocols it
implements.The grammatical rules in this document are to be interpreted as
described in RFC2234 (Augmented Backus-Naur
Form).The following constructs are introduced in this document to augment
RFC2234:Elements enclosed in braces (squiggly brackets) are treated as a
single, UNORDERED element. Its contents may occur in any order. Hence:
{elem foo} bar
would match (elem foo bar) and (foo elem bar).NOTE: Specifying alternatives is quite different from specifying set
grouping. Alternatives indicate the matching of exactly one (sub-)rule
out of the total grouping. The set mechanism indicates the matching of a
string which contains all of the elements within the group; however the
elements may occur in any order.A construct "#" is defined, similar to "*", for
defining lists of elements. The full form is "<n>#<m>element"
indicating at least <n> and at most <m> elements, each
separated by one or more commas (",") and OPTIONAL linear white space
(LWS). This makes the usual form of lists very easy; a rule such as
( *LWS element *( *LWS "," *LWS element ))
can be shown as
1#element
Wherever this construct is used, null elements are allowed, but do
not contribute to the count of elements present. That is, "(element), ,
(element) " is permitted, but counts as only two elements. Therefore,
where at least one element is required, at least one non-null element MUST
be present. Default values are 0 and infinity so that "#element" allows
any number, including zero; "1#element" requires at least one; and
"1#2element" allows one or two.A construct "&" is defined, similar to "#",
which uses an ampersand (&) instead of commas, and MUST NOT include
linear white space between elements.The grammar described by this specification is
word-based. Except where noted otherwise, linear white space (LWS) can be
included between any two adjacent words (token or quoted-string), and
between adjacent words and separators, without changing the interpretation
of a field. At least one delimiter (LWS and/or separators) MUST exist
between any two tokens, since they would otherwise be interpreted as a
single token.The following rules are used throughout this specification to describe
basic parsing constructs. The US-ASCII coded character set is defined by
CHAR =
UPALPHA =
LOALPHA =
ALPHA = UPALPHA / LOALPHA
DIGIT =
CTL =
CR =
LF =
SP =
HT =
<"> =
CRLF = CR LF
LWS = [CRLF] 1*( SP / HT )
TEXT =
COMMA =
]]>
Primary Social Data objects represent objects that are directly
addressable through top level API calls, such as osapi, RPC, REST
and Pipelining tags.An OpenSocial Activity represents a short summary or notification of a
timestamped event, often with pointers for more information.Activities are rendered with a title and an optional activity body. The title and body may be set directly as strings when calling
opensocial.newActivity. However, it is usually beneficial to create
activities using Message Templates for the title and body.Users have many activities in their activity streams, and
containers may not show every activity that is visible to a user. To help
display large numbers of activities, containers summarize a list of
activities from a given source to a single entry.You can provide Activity Summaries to customize the text shown when
multiple activities are summarized. If no customization is provided, a
container may ignore your activities altogether or provide default text
such as "Bob changed his status message + 20 other events like this."Activity Summaries always summarize around a specific key in a
key/value pair. This is so that the summary can say something concrete
(this is clearer in the example below).Other variables have synthetic "Count" variables created with the
total number of items summarized.Message ID of the summary is the message ID of the main template + ":"
+ the data keyExample summaries:
Field NameField TypeDescriptionappIdObject-IdSpecifying the application that this activity is associated with.bodystringSpecifying an optional expanded version of an
activity. Bodies may only have the following HTML tags: <b> <i>,
<a>, <span>. The container may ignore this formatting when
rendering the activity.bodyIdObject-IdSpecifying the body template message ID in the gadget spec.externalIdObject-IdAn optional ID generated by the posting application.idObject-IdAn ID that is permanently associated with this activity.mediaItemsArray<MediaItem>Any photos, videos, or images that should be associated with
the activity. Higher priority ones are higher in the list.postedTimestringSpecifying the time at which this activity took place in
milliseconds since the epoch.prioritynumberA number between 0 and 1 representing the relative priority
of this activity in relation to other activities from the same
source.streamFaviconUrlstringSpecifying the URL for the stream's favicon.streamSourceUrlstringSpecifying the stream's source URL.streamTitlestringSpecifing the title of the stream.streamUrlstringSpecifying the stream's URL.templateParamsA 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 personPersonKey.ProfileUrl. URL of the person's profilePersonKey.Id - The ID of the personPersonKey - Container may replace with DisplayName, but may also
optionally link to the user.titlestringSpecifying the primary text of an activity. Titles may only
have the following HTML tags: <b> <i>, <a>,
<span>. The container may ignore this formatting when
rendering the activity.urlstringSpecifying the URL that represents this activity.userIdObject-IdID of the user who this activity is for.A minimal Activity example:
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"
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.Discussion
As a person's actions become increasingly distributed, it is
important
to achieve a level of interoperability betweent the systems
that they
interact with. The Activity Streams specification has been
incorporated in order to improve interoperability with other systems
that may not be based on OpenSocial. This will provide implementors and
developers a wide range of options for incorporating social data within
their applications.
OpenSocial introduces support for the Activity Streams 1.0 specification following the pattern of support for
Portable Contacts. The data structures for ActivityObject and ActivityEntry are brought into Social-Data, an
new service is introduced in Social-API-Server, and application APIs are defined in Social-Gadget. In the
case of Activity Streams, there are several constructs that exist in OpenSocial that will be present in the
activity stream information that flows within a container and between external Activity Stream endpoints.
Included in the definition of the Activity Stream data structures in this specification are mappings to the
existing OpenSocial objects.
In its simplest form, an activity consists of an actor, a verb,
an an object, and a target. It tells the story of a person performing
an action on or with an object -- "Geraldine posted a photo to her
album" or "John shared a video". OpenSocial adds an
additional field to the data model, "actionLinks".
Because these are extensions, they are contained in an enclosing
namespace, "openSocial".Field NameField TypeDescriptionactorActivityObjectDescribes the entity that performed the activity. An activity MUST contain one actor property whose
value is a single ActivityObject.
contentstringNatural-language description of the activity encoded as a single JSON String containing HTML markup.
Visual elements such as thumbnail images MAY be included. An activity MAY contain a content property.
generatorActivityObjectDescribes the application that generated the activity. An activity MAY contain a generator property
whose value is a single ActivityObject.
OpenSocial note: If an OpenSocial application created the Activity Entry, this value SHOULD be the appId.
iconMediaLinkDescription of a resource providing a visual representation of the object, intended for human
consumption. The image SHOULD have an aspect ratio of one (horizontal) to one (vertical) and SHOULD
be suitable for presentation at a small size. An activity MAY have an icon property.
idstringProvides a permanent, universally unique identifier for the activity in the form of an absolute IRI.
An activity SHOULD contain a single id property. If an activity does not contain an id property,
consumers MAY use the value of the url property as a less-reliable, non-unique identifier. OpenSocial
note: The value of id MUST be the IRI form of the Global-Id.
objectActivityObjectDescribes the primary object of the activity. For instance, in the activity, "John saved a movie to
his wishlist", the object of the activity is "movie". An activity SHOULD contain an object property
whose value is a single Object. If the object property is not contained, the primary object of the
activity MAY be implied by context.
publishedstringThe date and time at which the activity was published. An activity MUST contain a published
property.
providerActivityObjectDescribes the application that published the activity. Note that this is not necessarily the same
entity that generated the activity. An activity MAY contain a provider property whose value is a
single ActivityObject. OpenSocial note: The
provider SHOULD be URL of the domain part of the Global-Id plus the OpenSocial service. Example:
http://mySocialNetwork.com/activitystreams
targetActivityObjectDescribes the target of the activity. The precise meaning of the activity's target is dependent on the
activities verb, but will often be the object the English preposition "to". For instance, in the
activity, "John saved a movie to his wishlist", the target of the activity is "wishlist". The
activity target MUST NOT be used to identity an indirect object that is not a target of the activity.
An activity MAY contain a target property whose value is a single ActivityObject.
titlestringNatural-language title or headline for the activity encoded as a single JSON String containing HTML
markup. An activity MAY contain a title property.
updatedstringThe date and time at which a previously published activity has been modified. An Activity MAY contain
an updated property.
urlstringAn IRI identifying a resource providing an HTML representation of the activity. An activity MAY
contain a url property.
verbstringIdentifies the action that the activity describes. An activity SHOULD contain a verb property whose
value is a JSON String that is non-empty and matches either the "isegment-nz-nc" or the "IRI"
production in RFC3339. Note that the use of a relative reference other than a simple name is not
allowed. If the verb is not specified, or if the value is null, the verb is assumed to be "post".
actionLinksArray<ActionLink>
An "openSocial" namespaced array of actionLinks associated with this Activity.
A complete ActivityEntry example
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 NameField TypeDescriptionkeystringA unique value with respect to the context it is being stored
within (typically a person).valuestringAn arbitary string.The first example is of a collection of key/value pairs for a
particular application/user pair:
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.
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 NameField TypeDescriptionidGroup-IDUnique ID for this group Required.titleStringTitle of group Required.descriptionStringDescription of group Optional. A Group example: Valid definitions for Message-Field are listed in the table below.DiscussionField NameField TypeDescriptionappUrlstringIdentifies the application that generated this message.bodystringThe main text of the message. HTML attributes are allowed and
are sanitized by the container.bodyIdstringThe main text of the message as a message template. Specifies
the message ID to use in the gadget xml.collectionIdsArray <string>Identifies the messages collection IDs this message is
contained in.idstringUnique ID for this message.inReplyTostringMessage 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" .../>recipientsArray <string>Array of person IDs.repliesArray <string>Array of message ids. Reference the sematics of the Atom
Threading model defined in rfc4685. URLs should be mapped to
Atom <link rel="type" .../>senderIdstringId of person who sent the message.statusstringStatus of the message. (NEW, READ, DELETED).timeSentDateUTC time message was sent.titlestringThe title of the message. HTML attributes are allowed and are
sanitized by the container.titleIdstringThe title of the message as a message template. Specifies the
message ID to use in the gadget xml.typestringThe type of the message.updatedDateLast update for this message.urlsPlural-Field <string>List of related URLs for this message. Supported URL types
include 'alternate', alternate for for this mailbox (text/html
being the most common).A Message example follows. For brevity, details of the 'sender' field,
an OpenSocial Person, are omitted. 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]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 person returned MUST include the "id" and "name" fields
with non-empty values, but all other fields
are optional, and it is recognized that not all Service Providers
are able to provide data for all the supported fields. The field
list below is broad so that there is a standard field name
available among Service Providers that do support any of these
fields. DiscussionThere are two special Person objects that can be requested
directly: the VIEWER and the OWNER. To understand the
distinction, imagine you're checking out a coworker's profile on
Orkut. In this case, you are the VIEWER and your coworker is the
OWNER. It's also common to view your own profile, in which case
you are both the VIEWER and the OWNER, and some applications may
choose to handle this case differently. OpenSocial also provides
for the case of anonymous viewing, where the gadget will not be
able to access the VIEWER's information.Person = "{"
"id :" User-ID ","
"displayName :" string ","
[ #Person-Field ]
"}"OpenSocial defines many common attributes associated with a person and is aligned with the Portable Contacts
specification. However, only display name and id are required and all others are optional. In practice,
support for these fields varies greatly among containers. As OpenSocial continues to be adopted as an
enterprise programming model, many of these fields are not appropriate based on the considerations of Human
Resource guidelines. DiscussionIn an attempt to balance the needs of consumer vs corporate
focused OpenSocial applications, and increase interoperability, the specification is refining attempting to
provide clarity around attributes that are broadly applicable across both the consumer and enterprise
domain, and those that are more appropriate for consumer oriented systems.
The generally applicable field definitions for Person are listed in the table below.Field NameField TypeDescriptionaboutMestringA general statement about the person.accountsPlural-Field <Account>An online account held by this Person.addressesPlural-Field <Address>A physical mailing address for this Person.alternateNamesPlural-Field <Name>List of alternative names. These may include known aliases, maiden-names, nicknames, acceptable
alternative forms of the same name (e.g. "James", "Jim", "Jimmy"), etc.appDataPlural-Field
<AppData>A collection of AppData keys and values.connectedBooleanBoolean 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.contactPreferencestringHuman-readable summarization of the Person's contact preferences. For instance,
a person may choose to specify something along the lines of, "Please
use instant messaging to contact me prior to calling."dnstringThis Person's X.500 'Distinguished Name'displayNamestringRequired. 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.emailsPlural-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.hasAppBooleanIndicating whether the user has application installed.idObject-IdRequired. Unique identifier for
the Person.imsPlural-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.locationstringnameNameThe broken-out components and fully formatted version of the person's
real name.nativeNameNameThe broken-out components and fully formatted, native-language version
of the person's real name.networkPresencePlural-Field <string>Person's current network status. Specified as one of: AWAY,
CHAT, DND, OFFLINE, ONLINE OR XA.organizationsPlural-Field <Organization>A current or past organizational affiliation of this Person.phoneNumbersPlural-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.photosPlural-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.preferredNameNameThe broken-out components and fully formatted version
of the person's preferred name.preferredUsernamestringThe 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.profileUrlstringPerson's profile URL, specified as a string. This URL must be
fully qualified. Relative URLs will not work in gadgets.publishedDateThe 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.relationshipsPlural-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.statusstringPerson's status, headline or shoutout.tagsPlural-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>
stringPerson's photo thumbnail URL, specified as a string. This URL
must be fully qualified. Relative URLs will not work in
gadgets.updatedDateThe 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.urlsPlural-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.utcOffsetDate-UTC-OffsetThe offset from UTC of this Person's current time zone, as of the time
this response was returned. The value MUST conform to the Date-UTC-Offset. Note that this value MAY
change over time due to daylight saving time, and is thus meant to
signify only the current value of the user's timezone offset.In addition to the table above, the socially oriented fields definition of the
Person include the following. Note that all extended properties are optional and may not be appropriate for use in all applications. DiscussionField NameField TypeDescriptionactivitiesPlural-Field <string>Person's favorite activities.agenumberThe age of this person. Sometimes sites might want to show
age without revealing the specific birthday.anniversaryDateThe 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.birthdayDateThe 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.bodyTypestringPerson's body characteristics.booksPlural-Field <string>Person's favorite books.carsPlural-Field <string>Person's favorite cars.childrenPlural-Field <string>Description of the person's children.drinkerstringPerson's drinking status.ethnicitystringPerson's ethnicity.fashionstringPerson's thoughts on fashion.foodPlural-Field <string>Person's favorite food.genderstringThe 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.happiestWhenstringDescribes when the person is happiest.heroesPlural-Field <string>Person's favorite heroes.humorstringPerson's thoughts on humor.interestsPlural-Field <string>Person's interests, hobbies or passions.jobInterestsPlural-Field <string>Person's favorite jobs, or job interests and skills.languagesSpokenPlural-Field <string>List of the languages that the person speaks as ISO 639-1 codes.livingArrangementstringDescription of the person's living arrangement.lookingForstringPerson's statement about who or what they are looking for, or
what they are interested in meeting people for.moviesPlural-Field <string>Person's favorite movies.musicPlural-Field <string>Person's favorite music.nicknamestringThe 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.notestringNotes about this person, with an unspecified meaning or usage
(normally notes by the user about this person). This field MAY contain
newlines.petsPlural-Field <string>Description of the person's petsorgIdentifierPlural-Field <string>Listing of this person's organizational identifiers (e.g. employee serial number,
student number, etc)politicalViewsPlural-Field <string>Person's political views.profileSongstringURL of a person's profile song.profileVideostringURL of a person's profile video.quotesPlural-Field <string>Person's favorite quotesrelationshipStatusstringPerson's relationship status.religionstringPerson's relgion or religious views.romancestringPerson's comments about romance.scaredOfstringWhat the person is scared of.sexualOrientationstringPerson's sexual orientation.smokerstringPerson's smoking status.sportsPlural-Field <string>Person's favorite sportsturnOffsPlural-Field <string>Person's turn offs.turnOnsPlural-Field <string>Person's turn ons.tvShowsPlural-Field <string>Person's favorite TV shows.A minimal Person example:
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 NameField TypeDescriptiondomainstringThe 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.usernamestringAn alphanumeric user name, usually chosen by the user, e.g.
"jsmarr".userIdObject-IdA user ID associated with this account.An ActionLink encompasses an action that a user may perform against an actionable resource.
It defines a caption for the action to perform, a URL to identify the target actionable resource,
and the HTTP operation to invoke the resource with.For example, an "Add Friend" button has a caption
(namely, "Add Friend") and references the resource that will be invoked when the button is clicked.Field NameField TypeDescriptioncaptionstringRepresents a hint that MAY be used by the presentation layer to allow interaction with the user, e.g. a button that invokes an POST.targetstringURL which represents the target web hook endpoint that can be invoked using the specified HTTP verb.httpVerbstringIdentifies the HTTP operation to perform against the actionable resource. Should be one of "GET", "PUT", "POST", "DELETE", or other standard HTTP verb. The HTTP verb is optional, and if omitted defaults to "GET".DiscussionAn object is a thing, real or imaginary, which participates in an
activity. It may be the entity performing the activity, or the entity
on which the activity was performed. Because Activity Streams are often
used in the context of a social platform, OpenSocial adds an
additional field to the data model, "deliverTo:".
Because these are extensions, they are contained in an eclosing
"namespace", org.opensocial.Field NameField TypeDescriptionattachmentsArray<ActivityObject>
A collection of one or more additional, associated objects, similar to the concept of attached files in an
email message. An object MAY have an attachments property whose value is a JSON Array ofActivityObjects.
authorActivityObjectDescribes the entity that created or authored the object. An object MAY contain a single author property
whose value is an
ActivityObject
of any type. Note that the author field identifies the entity that created the object and does not
necessarily identify the entity that published the object. For instance, it may be the case that an
object created by one person is posted and published to a system by an entirely different entity.
OpenSocial note: A common use case is for the "author" to be an OpenSocial. Containers SHOULD use the IRI
form of the
Global-Id
as the value.
contentstringNatural-language description of the object encoded as a single JSON String containing HTML markup. Visual
elements such as thumbnail images MAY be included. An object MAY contain a content property.
displayNamestringA natural-language, human-readable and plain-text name for the object. HTML markup MUST NOT be included.
An object MAY contain a displayName property. If the object does not specify an objectType property, the
object SHOULD specify a displayName.
downstreamDuplicatesArray<string>A JSON Array of one or more absolute IRI's [RFC3987] identifying objects that duplicate this object's
content. An object SHOULD contain a downstreamDuplicates property when there are known objects, possibly
in a different system, that duplicate the content in this object. This MAY be used as a hint for
consumers to use when resolving duplicates between objects received from different sources.
idstringProvides a permanent, universally unique identifier for the object in the form of an absolute IRI
[RFC3987]. An object SHOULD contain a single id property. If an object does not contain an id property,
consumers MAY use the value of the url property as a less-reliable, non-unique identifier.
imageMediaLinkDescription of a resource providing a visual representation of the object, intended for human consumption.
An object MAY contain an image property whose value is a
MediaLink.
objectTypestringIdentifies the type of object. An object MAY contain an objectType property whose value is a JSON String
that is non-empty and matches either the "isegment-nz-nc" or the "IRI" production in [RFC3987]. Note that
the use of a relative reference other than a simple name is not allowed. If no objectType property is
contained, the object has no specific type.
publishedstringThe date and time at which the object was published. An object MAY contain a published property.summarystringNatural-language summarization of the object encoded as a single JSON String containing HTML markup.
Visual elements such as thumbnail images MAY be included. An activity MAY contain a summary property.
updatedstringThe date and time at which a previously published object has been modified. An Object MAY contain an
updated property.
upstreamDuplicatesArray<string>A JSON Array of one or more absolute IRI's [RFC3987] identifying objects that duplicate this object's
content. An object SHOULD contain an upstreamDuplicates property when a publisher is knowingly
duplicating with a new ID the content from another object. This MAY be used as a hint for consumers to
use when resolving duplicates between objects received from different sources.
urlstringAn IRI [RFC3987] identifying a resource providing an HTML representation of the object. An object MAY
contain a url property
deliverTo:Array<Global-Id>Many social business systems incorporate the idea that an activity may not be public. By including the
"deliverTo:" field, a specific user(s) will receive the activity. The Activity MUST be delivered to the
recipients specified in the deliverTo: Array
An example ActivityObjectThe 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 NameField TypeDescriptionbuildingstringThe building identifier. DiscussioncountrystringThe country name component.floorstringThe floor identifier. DiscussionformattedstringThe 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.latitudestringExpresses the latitude of the location on a map.localitystringThe city or locality component.longitudestringExpresses the longitude of the location on a map.postalCodestringThe zipcode or postal code component.regionstringThe state or region component.streetAddressstringThe 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.typestringThe address type or label. Examples include 'work', 'home'.Albums support collections of media items (video, image, sound).Field NameField TypeDescriptiondescriptionstringDescription of the albumidObject-IdUnique identifier for the album.locationAddressLocation corresponding to the album.mediaItemCountintegerNumber of items in the album.mediaMimeTypeArray <string>Array of strings identifying the mime-types of media items in
the Album.mediaTypeArray <string>Array of MediaItem types, types are one of: audio, image, video.owernIdObject-IdID of the owner of the album.thumbnailUrlstringURL to a thumbnail cover of the album.titlestringthe title of the album.
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.
appId is an Object-Id for the application. DiscussionThe 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 NameField TypeDescriptionalbum_idObject-IdAlbum to which the media item belongs.createdstringCreation datetime associated with the media item -
assigned by container in UTC.descriptionstringDescription of the media item.durationintegerFor audio/video clips - playtime length in
seconds. set to -1/not defined if unknown.file_sizelongNumber of bytes (set to -1/undefined if unknown).idObject-IdId Associated with the media item.languagestringLanguage associated with the media item in ISO
639-3 format.last_updatedstringUpdate datetime associated with the media item -
assigned by container in UTC.locationAddressLocation corresponding to the media item.mime_typestringThe MIME type of media, specified as a string.num_commentsintegerNumber of comments on the media item.num_viewsintegerNumber of views for the media item.num_votesintegerNumber of votes received for voting.ratingintegerAverage rating of the media item on a scale of 0-10.start_timestringFor streaming/live content, datetime when the
content is available.tagged_peopleArray<string>Array of string (IDs) of people tagged
in the media item.tagsArray<string>Tags associated with this media item.thumbnail_urlstringURL to a thumbnail image of the media item.titlestringDescribing the media item.typestringThe type of media, specified as a MediaItem.Type object.urlstringSpecifying the URL where the media can be found.DiscussionSome types of objects may have an alternative visual representation in the form of an image, video or embedded HTML fragments. A Media Link represents a hyperlink to such resources.Field NameField TypeDescriptiondurationintegerA hint to the consumer about the length, in seconds, of the media resource identified by the url property.
A media link MAY contain a "duration" property when the target resource is a time-based media item such
as an audio or video.
heightintegerA hint to the consumer about the height, in pixels, of the media resource identified by the url property.
A media link MAY contain a height property when the target resource is a visual media item such as an
image, video or embeddable HTML page.
urlstringThe IRI of the media resource being linked. A media link MUST have a url property. OpenSocial note: Many
OpenSocial containers currently use
Media Items
as defined by this specification. When a container creates a Media Link that is based on a Media Item,
the Media Link URL MUST match the URL of the Media Item.
widthintegerA hint to the consumer about the width, in pixels, of the media resource identified by the url property. A
media link MAY contain a width property when the target resource is a visual media item such as an image,
video or embeddable HTML page.
mediaItemIdstringOptional. Provides a mapping from an Activity Streams MediaLink to an OpenSocialMediaItem. Identifies the corresponding MediaItem that
this MediaLink maps to, if any. This field is namespaced as an "openSocial" extension.
An example MediaLinkThe 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 NameField TypeDescriptionfamilyNamestringhe family name of this Person, or "Last Name" in most Western
languages (e.g. Smarr given the full name Mr. Joseph Robert Smarr,
Esq.).formattedstringThe 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.givenNamestringThe given name of this Person, or "First Name" in most Western
languages (e.g. Joseph given the full name Mr. Joseph Robert Smarr,
Esq.).honorificPrefixstringThe honorific prefix(es) of this Person, or "Title" in most Western
languages (e.g. Mr. given the full name Mr. Joseph Robert Smarr,
Esq.).honorificSuffixstringThe honorifix suffix(es) of this Person, or "Suffix" in most Western
languages (e.g. Esq. given the full name Mr. Joseph Robert Smarr,
Esq.).middleNamestringThe middle name(s) of this Person (e.g. Robert given the full name Mr.
Joseph Robert Smarr, Esq.).pronunciationstringA string describing the appropriate natural-language pronunciation of the name. DiscussionpronunciationUrlstringAn IRI to an audio resource illustrating the appropriate natural-language
pronunciation of the name. DiscussionDescribes 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 NameField TypeDescriptionaddressAddressThe physical address of this organization.departmentstringThe department within this organization.descriptionstringA textual description of the role this Person played in this
organization. This field MAY contain newlines.endDateDate or stringThe 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.fieldstringThe field the Organization is in.locationstringThe 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.namestringThe 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.salarystringThe salary the person receieves from the organizationstartDateDate or stringThe 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.subfieldstringThe subfield the Organization is in.titlestringThe job title or organizational role within this
organization.typestringThe type of organization, with Canonical Values job and school.webpagestringA webpage related to the organization.Describes a generic file or document.
Field NameField TypeDescriptionauthorPersonThe person who created the filedisplayNamestringThe natural-language, human-readable and plain-text title of the file.fileUrlstringThe IRI of the file described by this objectidstringThe unique identifier for the file objectpublishedstringThe optional time the file object was created in the form of an [RFC3339] "date-time"mimeTypestringThe MIME type of the file described by the object.updatedstringThe optional time the file object was last updated in the form of an [RFC3339] "date-time".urlstringThe permanent IRI of the file's HTML representation.Incorporate ActivityStreams 1.0 into OpenSocialProposal to Modify the Social Data Model in OS 2.0Person required fields inconsistencyMissing datatypes in message sectionKey words for use in RFCs to Indicate Requirement LevelsHarvard UniversityReserved Top Level DNS NamesIBMAugmented BNF for Syntax Specifications: ABNFASCII format for Network InterchangeSocial Graph Node MapperOpenSocial Core Data SpecificationOpenSocial Social Gadget SpecificationOpenSocial Social API Server Specification