OpenSocial Specification 1.0

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. Domain name examples use RFC2606.

OpenSocial is a set of APIs for building social applications that run on the web. OpenSocial's goal is to make more apps available to more users, by providing a common API that can be used in many different contexts. Developers can create applications, using standard JavaScript and HTML, that run on social websites that have implemented the OpenSocial APIs. These websites, known as OpenSocial containers, allow developers to access their social information; in return they receive a large suite of applications for their users. The OpenSocial APIs expose methods for accessing information about people, their friends, and their data, within the context of a container. This means that when running an application on Orkut, you'll be interacting with your Orkut friends, while running the same application on MySpace lets you interact with your MySpace friends. For more information on the types of information exposed by the OpenSocial API, see the Key concepts section. This document describes the concepts and principles behind the OpenSocial JavaScript APIs. It is a complement to the JavaScript API Reference, which covers the details of specific methods and parameters. This document does not describe any particular implementation of the API.

The OpenSocial Container. It is typically represented as a web page, but alternative forms that are capable of displaying a gadget, such as a personal computer desktop or a mobile device, are also accepted. The entity that has authored the gadget. The term "friend" is used throughout this specification and can be applied to a variety of relationships between people, whether or not they are actually friends, business contacts, or related through a management hierarchy. The "friend" term can be used to describe either symmetric relationships or asymmetric relationships (such as followers, as in Twitter). Also, this term can be used to refer to a human, a system, or another entity. For example, a user may "follow" updates from a bug tracking system. This may refer to any OpenSocial Person, though in most contexts it is referring to the Viewer of the gadget at runtime. The primary entity in a gadget that will be displayed to an end user. Currently only two types of Content are supported by OpenSocial: Type HTML gadgets are the most prevalent, and are imbued with the most rich feature set. Code is provided directly in the gadget XML content section for rendering and control flow. This code simply assumes that functionality is available that has been requested from whatever gadget features were declared. In the case of optional-declared features, a simple feature-existence API can and should be consulted to ensure the capability is enabled. The code is processed by a gadget server and rendered in an IFRAME. Type URL gadgets only specify a base URL. A standard set of parameters are added to this URL by the gadget server, which renders the gadget in an IFRAME. The application to which the URL points must include a referenced JavaScript library using a <script> tag as it renders, to enable gadget APIs to be made available. Type URL gadgets can't take advantage of all features, notably features that manipulate HTML and JavaScript code directly. However, this gadget type has proven highly useful for turning existing web sites or applications into gadgets. Multiple Content sections may be specified in gadget XML. Each is labeled with one or more optional view identifiers, which allow the gadget to behave or appear differently depending on the context in which it's rendered. This context is provided by the gadget container. Any piece of information attached to a gadget, such as a title, author name, or description, that provides processing instructions to the Container, or otherwise does not directly impact gadget rendering. A library or behavior that is provided by the Container and triggered by use of the /ModulePrefs/Require or /ModulePrefs/Optional tags. Gadget features are the primary extensibility mechanism employed by gadgets. They often direct a gadget server to make new JavaScript APIs available to rendering code, but may also manipulate the gadget's contents, for example to add extended syntax. Examples of gadget features include OpenSocial (provides gadgets with a rich set of social APIs), dynamic-height (enables gadgets to resize themselves to an appropriate height), and tabs (a UI library facilitating tabular navigation). Message bundles are XML documents containing localization information. They allow developers to internationalize their gadgets simply by adding name/message mappings corresponding to whatever languages the developer chooses to support. These messages may be accessed programmatically through the core JavaScript APIs provided to all gadgets, or may be statically substituted into code using simple syntax. Referred to as "user prefs" or "prefs", these represent configuration values for a User of the gadget. These are key/value pairs that form the basis of gadget configuration and persistence. They are most often manipulable by users of the gadget, and are persisted on behalf of a user so that the gadget has access to them across multiple rendering requests. The gadget container is typically responsible for providing their persistence for this data and an interface to edit it. Generally referred to as "gadget spec", or simply a "gadget", this is the XML document that contains all the Metadata, Features, Message Bundles, User Preferences, and Content necessary to display a gadget to an end user. A gadget spec is authored by a Developer and made available through a public web server at a well-defined URL so that Containers may use this URL as a canonical reference for retrieving updates to the gadget. Any system used to hold a repository of gadgets that may be installed by Users. A presentation mode for a gadget.

OpenSocial defines the following levels of compliance, each of which defines an encapsulated set of capabilities. OpenSocial has been structured this way to support a wide array of adoption use cases that are all considered compliant with the specification. For example, it is possible to only offer social APIs via REST and be considered a compliant OpenSocial Social API Server. Likewise, some implementers may choose to leverage only the gadget aspect of specification. In this case, they can be considered to be a compliant OpenSocial Core Gadget Server. To be considered a Core API Server, a site MUST fulfill all the requirements defined in the Core API Server Specification. To be considered a Gadget Container, a site MUST fulfill all the requirements defined in the Core Gadget Specification. To be considered a Social API Server, a site MUST be a Core API Server and MUST fulfill all the requirements defined in the Social API Server Specification. To be considered a Social Gadget Container, a site MUST be a Core Gadget Container and MUST fulfill all the requirements defined in the Social Gadget Specification. To be considered an OpenSocial Container, a site MUST fulfill all the requirements for an Social API Server and a Social Gadget Container. In all cases, a site MUST fulfill the requirements in Extensions.

The objective of the OpenSocial extension model is to allow the specification to mature by adding depth and richness to a set of existing features while at the same time fostering organic growth of new capability. That is, it should be possible to enhance existing features as well as add new ones. A robust extension model enables the OpenSocial community to manage the overall complexity of the specification in a clearly documented consistent manner. This model has the following benefits to the OpenSocial community: Keeps the core specification focused on defining the base programming model and social constructs. Lowers the barriers of entry thereby promoting adoption and increasing compatibility between implementations. Fosters the evolution of niche-features while avoiding anarchy. This section defines the kinds of enhancements that we envision being made to OpenSocial, as well as the rules they must follow in order to be accepted into the specification. An extension is defined in a document, called an OpenSocial Enhancement (OE), with language and formatting that is consistent in terminology and semantics with the specification. As the extension develops, it MUST conform to the guidelines and life cycle defined in the OpenSocial Development Process. For example, extensions are required to provide a publically available prototype that demonstrates that it can be implemented as well as a corresponding set of test cases. Extensions MUST be defined in a manner that is consistent with the programming model defined in the versions of the specification to which they apply. Containers that offer OpenSocial extensions MUST adhere to the requirements specified in this specification as well as any requirements specified in the extension document. Generally speaking, we anticipate OpenSocial to be extended following three patterns. Not coincidentally, these extension patterns follow the typical use cases of OpenSocial that are reflected in the structure of the specification. Adding a new gadget feature Extending the social data models Extending the protocol

The OpenSocial programming model consists of a collection of Javascript APIs declared as features. There are two kinds of features, core and optional. For example, the core API gadgets.viewes.View defines how gadgets work with and request different amounts of real estate in the browser. An example optional feature is gadgets.skins.. Because of the existing separation between core and optional features, OpenSocial is already layered to handle gadget extensions. In order to avoid undue burden on implementation of domain specific or container specific behavior, extensions MUST NOT be required. As OpenSocial becomes deployed more widely, the number of extensions will increase. It will be important that new features avoid clashing with those currently defined in the specification. New features that are proposed for inclusion of OpenSocial MUST NOT use any existing namespaces that are already part of the specification. It is the responsibility of the developer proposing the new feature to avoid namespace collisions. Features that are progressing through the OpenSocial enhancement lifecycle MUST include the lifecycle designator for the stage they are in as the suffix, delineated by a “.” of their name. For example, suppose that pub-sub is being proposed as a new feature. The community has been working on it and a proposal is available publically. The feature name should be: “pub-sub.incubating”

An example module definition would be: <Module> <ModulePrefs title="Social Activities World" icon="http://localhost:8080/gadgets/files/samplecontainer/examples/icon.png"> <Require feature="opensocial"></Require> <Require feature="pub-sub.incubating"></Require> </ModulePrefs> …. This intent is to clearly indicate gadget developers that the OpenSocial community has not officially adopted the feature. Upon acceptance of the proposal as part of the specification, the feature name MUST drop the life cycle designator.

OpenSocial defines a set of data models that are used to represent the social constructs in your system, e.g. people. An set of fields has been defined for each one of these constructs. The initial motivation for these fields was driven primarily from the standpoint of Social Networking. Fortunately, as OpenSocial begins to be used in more specialized domains, the programming model is flexible enough to accommodate these new fields. However, care must be taken as extensions are introduced in order to avoid issues such as collisions in the attribute names of the returned JSON Objects. Therefore, extensions SHOULD use a prefix that uniquely identifies the extended fields. This prefix SHOULD be an underbar '_'. If a feature is also added as part of the extension, the data model prefix SHOULD match a namespace declared in the Javascript. It is possible to simply append new fields into the existing models and some providers currently follow this approach. However, it is RECOMMENDED that extensions to the OpenSocial data models be encapsulated in their own node. This will provide a level of isolation and layering within the models and provide a consistent extension pattern.

In OpenSocial 1.0, the canonical XSDs do not contain extension points, e.g.xs:any. Therefore, XML instance documents of extensions that have added attributes ore elements to the data model or gadget metadata will not validate. Therefore, extensions MUST NOT require schema validation. Containers that are not supporting extensions MAY validate the gadget metadata and the data models.

Below is an example of how the Person model has been extended by two fictional organizations, Acme and DevWorld. Acme has been using OpenSocial for some time, and has extended the model by appending a field, "Employee Number" directly into the data model. This approach should be used for backwards compatibility with existing extensions. As new extensions are proposed, they should follow the pattern illustrated by DevWorld, which creates a containing element, "devWorldData", for their additions to the model.

Assuming the extensions have been made available via features to the container, here is the example REST call that would retrieve the data. Notice in the request the use of the name and underbar prefix, e.g. "devworld_", to help avoid collisions. In this example, DevWorld allows their users to assign nicknames. Without a prefix, this would clash with OpenSocial's Person nickname.

The result of this request will produce an XML document with the following structure. 1122998877 devworld_nickname The Wiz... devworld_platform Mac john.doe Doe John Doe John ]]>

Omitting the "type=XML" query parameter from the request will return a JSON document.

In some cases, it will be necessary to add APIs to support additional use cases outside the initial intent of the specification. For example, an alternate security model or payment API may be introduced. In these scenarios developers MAY extend OpenSocial by introducing new APIs. These kinds of additions to OpenSocial are called "protocol extensions" because they introduce new APIs. It is important that these APIs be consistent with the existing programming model. Protocol extensions MUST maintain the semantics of the OpenSocial and MUST NOT modify any API defined by the specification. Protocol extensions MUST provide endpoints in the required protocols as defined by the specification, e.g. XML, JSON, ATOM. Protocol extensions SHOULD provide extensions for each level of compliance as defined by the OpenSocial specification, e.g. REST APIs for the OpenSocial server as well as constructs to support OSML and templating.