OpenSocial Specification Release Notes

Published November 18, 2010 As OpenSocial continues to be adopted, especially in enterprise environments, there was a desire by the community to include support for advanced mashup scenarios, specifically, those where gadgets could securely message each other in a loosely coupled manner. OpenSocial 1.1 includes support for this capability, informally known as pub-sub.

Version 1.1 officially support an inter-gadget eventing system based upon the OpenAjax Hub. "The OpenAjax Hub is a set of standard JavaScript functionality defined by the OpenAjax Alliance that addresses key interoperability and security issues that arise when multiple Ajax libraries and/or components are used within the same web page." By incorporating this technology into OpenSocial, gadgets are now able to declare, as part of the module definition, events to which they are able to publish and subscribe. In addition, this specification has reserved several topic namespaces for use by OpenSocial. Please refer to the Inter-Gadget Eventing in the Core-Gadget specification for more information.

Version 1.0 of the specification contained duplicate language and inconsistencies in the language around the use of OAuth. This version attempts to clean up these and present a more consistent usage model.

Published March 9, 2010 With so many different types of websites adopting OpenSocial it has become clear that a "one size fits all" approach isn't appropriate for the OpenSocial spec. Containers have different types of data they want to make available to clients (sometimes it's social data, sometimes it's not), and some want to expose that data via web services, while others wish to use gadgets. As such, modularity was a key goal in the OpenSocial 1.0 iteration, allowing implementers to pick and choose the elements of OpenSocial that make sense for their use cases. OpenSocial 1.0 also defines extension points so containers can add functionality not covered in the spec, but do so in a standard way, making it easier to fold such extensions back into the spec or share extensions across containers.

To accommodate the varied use cases of OpenSocial containers, the Compliance section has been revised to include four compliance models: Core API Server - For containers that wish to expose data in a standard way though web services. Core Gadget Server - For containers that simply want to be able to render gadgets. Social API Server - For containers that wish to expose social data through standard web services that are consistent across containers. Social Gadget Server - For containers that want to render gadgets and provide them access to standard social data. The spec itself has been reorganized along these lines as well, consolidating all data definitions into the Core-Data.xml and Social-Data.xml files, and creating a separate file for each of the four compliance models.

A new Extensions section defines how containers can extend OpenSocial in a common way so that extensions can be shared across containers, even if they're not appropriate for the official OpenSocial spec.

Features included in a gadget spec should now be versioned. If no version is specified, the default value is '1.0'. OpenSocial v0.9 defined a groups REST service, so OpenSocial 1.0 adds definitions for the JavaScript API and RPC endpoint. The opensocial.* namespace has been largely deprecated in favor of the osapi.* API. Added text to make it clear the 'friend' may refer to any relationship (e.g. colleague, classmate, etc.). Variables may be declared in both inline and custom tag templates with the os:Var tag. This tag may also be used data pipelining to declare global literal variables. The spec now decalres that variable keys are case-sensitive both for Data Pipeline tags and for template parameters. Added a 'Request' field to the object returned in data pipelining responses so developers can access information about the request that initiated the request. Introduces a "SecurityProfile" feature that gadgets can include to specify if they want EL functions to HTML escape strings or not. Added language stating that only one value is allowed for a given parameter and define behavior where namespaces are used. The content in this section was split up and distributed to the appropriate sections in the spec. For example, the overview of data objects like people, activites, and messages now live in Social-Data.xml Added documentation for the elements in a gadget XML spec and removed the Metadata and JavaScript Request sections. MediaItem object now have a 'title' field and the 'caption' field has been deprecated. The spec now uses 'birthday' throughout. Several typos and inaccuracies that we're pointed out since v0.9 was published.

Several field names have been changed. Containers should continue to support the old values to avoid breaking existing gadgets. App developers should use the new field names for all new gadgets. Old field name New field name Account.useridAccount.userId Address.extendedAddressRemoved. Use Address.streetAddress Address.poBoxRemoved. Use Address.streetAddress Album.captionAlbum.title Name.additionalNameName.middleName Person.appdataPerson.appData Person.dateOfBirthPerson.birthday Person.languagesRemoved. Use Person.languagesSpoken

Published April 15, 2009 The major focus of OpenSocial v0.9 was to make application development, testing, and deployment easier and faster, while reducing the learning curve for new app developers.

OpenSocial v0.9 introduces a new Lightweight JavaScript API that makes requesting and parsing data simpler. The new API has all the power, flexibility and granularity of the old one, but the code speaks for itself:

Requesting the viewer in OpenSocial v0.8 var req = opensocial.newDataRequest(); req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.OWNER), "req"); req.send(callback);

Requesting the viewer in OpenSocial v0.9 osapi.people.getViewer().execute(callback); For backwards compatibility, the new API is available in a separate namespace, “osapi” which can be activated with a <Require feature="osapi"> directive. All the old APIs are still available via <Require feature="opensocial-0.9">, so existing applications can continue working. However, for new application development, the new lighter API is the smarter choice. Not only will you save time typing, but your JS code will be significantly reduced, improving download times.

In its first iterations, OpenSocial was limited to running AJAX applications inside social networks. However, testing an app that is rendered by someone else's server has proven difficult and the heavy reliance on JavaScript meant that lots of server-side web programming skills were under-utilized. Some developers even come up with ways to cram their old way of developing web applications into the OpenSocial model – using a makeRequest() to download HTML contents from a URL on their servers, and then stuff the result into an element’s innerHTML somewhere on the page. Clearly these developers were sending us a powerful signal we couldn’t ignore. Proxied Content is a formal way for the same use case to be achieved. It allows developers to specify a URL for a given <Content> block in their gadget spec rather than inline JavaScript and HTML.

An example of proxied content <Content view="home.about" href="http://www.example.com/about.html"> When the given view is requested, the container will make a request to the URL specified (or fetch the data from cache) and render the HTML returned directly in the browser. This small code change introduces several advantages: Provides a simpler pathway for converting existing web applications into OpenSocial apps. Allows containers to sanitize content before rendering, protecting all the parties involved. Reduces the number of server round-trips required to render an application, especially when combined with data pipelining. Fewer round trips significantly reduces latency for end users.

A common pattern in OpenSocial apps to date is for apps to request social data from the container when first loaded using a DataRequest, then send that data to remote servers using a makeRequest. Using JavaScript to perform these operations requires the container to load the app's IFrame before any requests are made, leaving the end user staring at a 'Loading...' message. Data Pipelining defines a simple declarative XML language that allows the developer to specify what social data their application will need, so the container can make that data immediately available by including it in the app's IFrame. When used with proxied content, the social data is sent to the URL specified in the href attribute of the <Content> element.

Using data pipelining and proxied content <Content type="html" href="http://www.example.com/userInfo.php"><![CDATA[ <script xmlns:os="http://ns.opensocial.org/2008/markup" type="text/os-data"> <os:ViewerRequest key="viewer"/> </script> ]]></Content> In this example, the container sends the viewer's information to the given URL (i.e. http://www.example.com/userInfo.php), where the PHP file can access the viewer's ID and return HTML containing the appropriate information for that user.

Until now, the standard approach to rendering data into OpenSocial apps has involved manipulating a DOM element's innerHTML and/or dynamically creating DOM elements. These methods for generating UI can be unwieldy, difficult to maintain, and aren't easily reusable. For example, imagine handing off the following snippet to a HTML/CSS programmer to improve the UI design:

var link = document.createElement('a'); link.href = song.url; document.getElementById('outputDiv').appendChild(link); var img = document.createElement('img'); img.src = song.albumThumbnail; link.appendChild(img); link.appendChild(document.createTextNode(song.title + ' BY ' + song.artist + ' FROM ALBUM ' + song.album)); OpenSocial Templates give you a straightforward approach to creating data-driven UI in OpenSocial gadgets while separating markup from programming logic. The result is code that is cleaner, more streamlined, reusable, and much easier to maintain. With OpenSocial Templates, the example above becomes more HTML-friendy:

Several changes to ensure that the data formats for OpenSocial REST and Portable Contacts are compatible. Adds support for startIndex and count parameters when requesting activities. Adds support for rewriting the content of a gadget and allows developers to control the behavior of the rewriter by introducing a new optional feature "content-rewrite". The content-rewrite feature defines a set of rewriting operations that a container can perform on rendered and proxied content and rules to allow developers to control which content the rewriter can operate on. Adds support for accessing photos and other media items. Allows upload of files through REST and JSON-RPC calls to the OpenSocial container. This mechanism can be used to support many capabilities such as uploading audio/video/image content to the container for inclusion in a user's album or creating activity stream entries that contain uploaded media item content. Exposes JavaScript functions which can be used by developers and libraries to output logging information. This creates a single place for developers to look when debugging their application, smoothing over a barrier to adoption. Adds internationalization support for currency, date time, and numeric formatting. Provides an additional mechanism for gadget developers to control the lifecycle of specific HTTP content cached by OpenSocial containers beyond what is already available through standard HTTP cache control headers. This capability allows developers to explicitly invalidate the content the container has fetched on behalf of a user (via proxied rendering or authenticated/signed makeRequest calls) and static resources such as gadget specs and message bundles Extends the current messaging model to support read/write access via JavaScript and REST/RPC. Using OAuth from a gadget requires opening a pop-up window to the OAuth service provider. We've added a JavaScript method to handle the some nuances required to get this right and provide a good user experience, such as avoiding popup blockers and detecting when the popup has been closed. Allows developers to define named views in their gadget spec and navigate to these views using JavaScript or templates. Allows per-user key/value pairs stored on the container to be accessed as if they were extended profile fields.

None

Published September 25, 2008 The server-to-server protocols are the primary focus of version 0.8.1. The Person schema has been aligned with the Portable Contacts effort, and an optional RPC proposal has been added.

Server to server functionality has been expanded with the addition of a JSON RPC protocol, which will allow for simpler batching of requests. To maintain naming consistency, the RESTful API is now known as the RESTful protocol. OpenSocial IDs may now contain "-", "_", and "." in addition to alphanumeric characters.

The RESTful protocol has renamed or deleted many query and response fields. Please consult the following list of RESTful protocol changes for more detailed information.

By implementing the RESTful protocol, a container now becomes technically compatible with the Portable Contacts specification. Many of the following changes were implemented to facilitate this compatibility. Requests will support the format=xml parameter. People requests must be made in either format=xml or format=json. Containers are now required to implement paging of results via the startIndex and itemsPerPage parameters. This parameter has been removed from JSON Collection responses. This parameter has been removed from JSON collection responses. It should be possible to return all the requested contacts in a single request, however containers may choose to limit the maximum items returned per request for performance reasons. It is up to each container to define the number of contacts returned when no itemsPerPage parameter is specified in a request. The orderBy parameter has been renamed to sortBy. A new sortOrder parameter has been introduced, with values ascending and descending. The default value of sortOrder is ascending. Queries may now specify that results only contain entries that have been updated in a specified interval. Since sorting and filtering on arbitrary fields can be too expensive for a container to support, responses now contain top-level response fields filtered, sorted, and updatedSince, to indicate whether the content in the response was filtered according to the original request. Using a new @deleted selector and the updatedSince parameter, it is possible to retrieve all contacts that were deleted since the supplied date. Containers must return at least a name and an id when returning Person data. The value returned in the profileUrl Person field MUST also be returned in the urls field, as a type=profile entry. Person records now include a photos field, which will contain a list of entries with sub-fields url, type and primary. If the thumbnailUrl field is returned on a Person object, this url must also be present in the photos field, as a type=thumbnail entry. Person records now include an ims field, which will contain a list of entries with sub-fields value, type,and primary. The type values of "aim", "gtalk", "icq", "xmpp", "msn", "skype", "qq" and "yahoo" are defined to match several commonly used services, although new types may be defined as well. Person records now include an accounts field, used to represent other services where the Person has accounts. This field will contain a list of entries with sub-fields domain, userid, username, and primary. The emails, urls, ims, phoneNumbers, addresses, organizations, and photos Person fields will recieve an additional primary sub-field which will indicate which field in the list (if any) is the "primary value" of that type. Entries for jobs and schools will be combined into one array of Organization structures named organizations. The Organization structure will be extended with a type sub-field, with canonical values of "job" and "school". The primary textual value of plural Person fields should be stored in a sub-field named value. This will require renaming emails.address, phoneNumbers.number, urls.address and all instances of the {Enum}.key field to {Enum}.value. The addresses, accounts, and organizations fields are complex and do not have the concept of a value field. For the purposes of sorting and filtering, the corresponding "primary" sub-fields on these fields will be addresses.formatted, accounts.domain, and organizations.name. Person records will now treat gender as a string field, with the canonical values of "male" and "female". The extendedAddress and poBox Address subfields have been removed in favor of storing a complete (and potentially multi-line) address in the streetAddress sub-field. The unstructuredAddress sub-field of an Address is renamed to formatted. The dateOfBirth Person field is renamed to birthday. The timeZone Person field is renamed to utcOffset. The nickname Person field is now defined as "the casual way to address this person in real life". If a Person request is missing the fields query parameter, the minimal set of fields that must be returned by default have been defined as id, name, and thumbnailUrl, to match the defaults for the JS API. The RESTful protocol now defines the endpoints /people/@supportedFields and /activities/@supportedFields, which will return lists of the Person and Activity fields supported by the container. The indexBy query parameter has been removed. The Activity title field is now treated as a string that may contain HTML markup, instead of a complex data object. The unstructured Name field is renamed to formatted. The displayName field is added as a required top-level Person field.

A new, optional JSON RPC protocol has been introduced to simplify batching and complex server-to-server operations.

This enum may be used to construct an IdSpec object, using either the values of opensocial.IdSpec.GroupId.FRIENDS and opensocial.IdSpec.GroupId.SELF. The return values for opensocial.Environment.supportsField() calls have been defined as true when a container supports a field, and false otherwise.

The <Preload> element now supports the value of "oauth" for its authz attribute. If authz=oauth is specified, then the oauth_service_name, oauth_token_name, oauth_request_token, and oauth_request_token_secret attributes will be accepted. These attributes have the same semantics and defaults as their corresponding gadgets.io.makeRequest parameters.

Published May 27, 2008

The OpenSocial specification now requires that containers implement a REST based API according to the RESTful API specification. This allows for servers, mobile devices, and desktop applications to interact with OpenSocial containers. See the specification for details.

Version 0.8 introduces several changes to the OpenSocial JavaScript APIs that are not compatible with previous versions. Because most containers support multiple API versions, existing gadgets will continue to use the 0.7 API and will work as before. However, gadgets that are updated to take advantage of 0.8 features will have to use the newer versions of these changed APIs. The incompatible changes are: Instead, use an IdSpec object with the appropriate NETWORK_DISTANCE parameter. See the API documentation for details. opensocial.Person.Field.LOOKING_FOR used to return a string, now returns an opensocial.Enum.LookingFor object.

Automatic data escaping has become easier to control with the addition of an escapeType parameter to the newFetchPersonAppData and getField methods, which allow a developer to specify whether the returned data should be escaped. All data stored in the Persistence API is now treated as JSON-encoded. This allows for easier storage of complex objects as well as smart data escaping by the container. The newRemovePersonAppDataRequest method was introduced to allow developers to delete stored data from the Persistence API. The Person object has new hasApp and networkPresence fields. The lookingFor field has been changed to a more structured format. The new IdSpec object provides a structured way to define a group of people, including a NETWORK_DISTANCE parameter which will allow for querying friends of friends. The new topFriends and isFriendsWith fields allow developers to filter the results of Person requests in new ways. The Message object now has titleId and bodyId fields so that messages can use templates in the same way that activities do. Responses may now contain the new limitExceeded error code to indicate that a quota was exceeded by the request. The getContainerUrlTemplate method was added to simplify constructing navigation URLs.A container is now able to specify a template for the application's URL, so developers can construct navigation links without making synchronous JavaScript calls. The requestShareApp method now lets the developer set navigation targets that application users will see, both after accepting invites and also when sharing the application with friends.

The gadgets.io.AuthorizationType.AUTHENTICATEDparameter has been deprecated in favor of the newly added gadgets.io.AuthorizationType.OAUTH. Gadgets may now consume web services requiring OAuth authorization. The description of signed makeRequest calls has become much more detailed in the spec. The names of parameters that containers may or must include have been standardized, and key management practices are spelled out in detail. Calls to gadgets.io.getProxyUrl and gadgets.io.makeRequest may now include a parameter specifying how often the container should refresh the content which lives at the supplied URL. Calls to gadgets.views.requestNavigateTo may now specify an OWNER's ID number in order to navigate between viewson different users' profiles. The gadgets.util.sanitizeHtml method was added to convert potentially malicious HTML code to text safe for display. The gadgets.views.ViewType enumeration has been modified to reflect the most well-known set of views: HOME, PROFILE, CANVAS, and PREVIEW. The new PubSub feature enables developers to send data between multiple gadgets on the same view.

Message bundles can now be inlined into the gadget XML, and no longer have to be in a separate file. Gadgets can use the new <Preload> element to instruct the container to fetch data from a remote source during the gadget rendering process. This data will be inlined in the rendered output and available immediately when gadget code is executed. Use of this method should reduce latency for gadgets that depend on content from remote servers to render. The new <Preload> element also supports preloading responses from signed requests. Developers should add the authz="signed" attribute and value to the <Preload> element to specify that a request for the URL should be signed by the container. There is a new <Link> element that can be used within the gadget ModulePrefs section. This change is intended to allow containers to support new link types, such as gadgetsHelp and gadgetsSupport. To improve localization support, substitutions are now supported for all hangman variables that get displayed to users (e.g. all Module.ModulePrefs attributes, UserPref@display_name) The ModulePrefs section can now be used to specify URLs for usage of OAuth. Gadgets now support lifecycle events. You can place link tags in gadget xml that specify URLs the container should hit when a specified type of event occurs. This way, a gadget can be notified of all app installs or uninstalls. You can use the new preferredHeight and preferredWidth tags to specify default height and width for each Content section.This means that gadgets with multiple views can have different default heights.

Published January 25, 2008 Version 0.7 of the OpenSocial JavaScript API is intended to be the first iteration that can fully support rich, social applications. All features are covered in the API Reference (v0.7), but differences between version 0.6 and version 0.7 are explained in this section. This release adds a slew of standard fields that you can access about a Person. These include location, schools, pets, movies, sports, and more. However, keep in mind that a container may not have all of this information available so your application should always check first by using the supportsField method. Two new methods allow your application to send messages on behalf of a user. You can invite a user's friends to install your application with the requestShareApp method. You can also send an application-specific message with the requestSendMessage method. Both of these methods require the user sending the message to authorize the request first. You can now define activity messages with placeholders for pieces of applicaton or user data. This separation of data and presentation allows multiple activities to be combined into activity summaries?consolidated bundles of activities that let users know what their friends are up to without having to wade through a flood of messages. For example, instead of seeing five new updates about friends that installed a new application, you would see one update that says five of your friends added the application. For details on how to use activity templates in your application, see opensocial.Activity in the OpenSocial API reference. Support for global and instance-scoped application data has been removed from the API. Global application data can be implemented using feeds (that can be prefetched for performance) and other web standards. Instance-scoped application data can be implemented on top of user-scoped data by including the module ID of the application in the key.

As part of the Apache Shindig project, gadgets have been open sourced. The new Gadgets Specification defines the gadgets.* JavaScript namespace where you'll find that some of your favorite methods from the Gadgets API have been re-namespaced into a cleaner API for your convenience and clarity. For example, _IG_Adjust_IFrame_Height is now available as gadgets.window.adjustHeight (and don't worry, these updates are backwards compatable, so the old methods will work with Shindig-based renderers). Some notable updates in the Gadgets API include: The Gadgets API provides methods that allow your application to get more information about how a container will render your gadget. You can get information about the dimensions available for your gadget with gadgets.windows.getViewportDimensions, and obtain information for internationalization, such as the country and language of the user, using the gadgets.Prefs object. You can also use the gadgets.skins.getProperty method to get information about the look and feel of the container, such as the color of the font or background. The methods for getting the current view, or navigating between views, have been removed from the Environment class and now live in the gadgets.views.* namespace. The Gadgets XSD has been extended to support multiple <Content> blocks, where each <Content> block declares the views it should be rendered on. You can also use gadgets.views.getCurrentView to get the current view at run-time. For more information, see the Gadgets Specification. The makeRequest method has been moved from the opensocial.* namespace to gadgets.io.makeRequest. Also, two new fields, HEADERS and POST_DATA, have been added to gadgets.io.RequestParameters so you can now send arbitrary HTTP headers or POST data in your request. The hasCapability method has been removed from the opensocial.Environment class. To check whether a function is supported by your current container, you now use gadgets.util.hasFeature. You can now use the stringify and parse methods of the gadgets.json.* package to store objects using the Persistence API without having to import a third-party library. See the OpenSocial API Reference for more info.

Published December 21, 2007 The OpenSocial JavaScript API (v0.6) introduces several new features. These are all covered in the API Specification (v0.6), but differences between version 0.5 and version 0.6 are explained in this section. The new Environment class includes a hasCapability method that takes a function name and tells you if that function is available in your current container. It also includes a supportsField method to check if a particular field is supported in person or activity objects. These new methods allow apps to cleanly handle container-specific extensions if they're provided. The Environment class also includes a getDomain method, which tells you which site you are in (such as orkut.com or myspace.com). However, keying on domain should only be used if the more explicit environment variables aren't sufficient. This release also adds a new Surface class. You can use opensocial.requestNavigateTo to take your gadget from one page of a container to another (for example, to link the profile to the canvas page). This call takes a Surface object, which you get from an Environment object (opensocial.getEnvironment()). The environment's getSupportedSurfaces method tells you which surfaces the container supports, and getSurface tells you which one you are currently on. The getParams method returns all of the parameters passed in by the requestNavigateTo call if any were requested. The Surface class currently has only two methods, getName and isPrimaryContent, but more methods may be added as the API progresses. The beginning of tighter permission control is introduced in v0.6. Now, when a gadget uses a data request to fetch a viewer from the server, it is only returned if that gadget has access. If the gadget does not have access, one of the newly defined standard error codes, opensocial.ResponseItem.Error.UNAUTHORIZED, is returned instead. A gadget can also check ahead of time for its access by using the new opensocial.hasPermission call. If access is denied, you can use opensocial.requestPermission to ask the viewer for the specified permission. Of course, some containers may always grant viewer access, and some may always deny, but now this decision is up to the container. Another addition to the API is the new opensocial.makeRequest method. This is an enhancement to the current gadget API IG_Fetch... methods. The opensocial.makeRequest method allows for POSTs as well as GETs, and you can specify whether you want your data fetch to be signed or even authenticated. The Stream class is gone, and its fields are now part of the Activity class. The summary field on the Activity class has been removed because title and body seem to be sufficient for most developer's needs. Folders were deprecated in 0.5 and have been completely removed now. When requesting people, instead of using broad categories (e.g. BASIC, MATCHING, FULL, and so on) for the opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS value, you can now specify an array of Person fields (which you should check in advance with the supportsField method). Specifying fields instead of categories allows you to tailor the calls to deliver exactly what you need. Lastly, the init method on the container has been deleted. Make sure to use the requires tag in your gadgets to fetch opensocial. All other ways of initializing opensocial in your gadget are deprecated.