OpenSocial Specification 2.5.1opensocial-and-gadgets-spec@googlegroups.com
General
OpenSocialsocial networkingRESTXMLExtensible Markup LanguageJSONJavaScript Object NotationAtomThe key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
RFC2119.Domain name examples use RFC2606.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. Note: The
Core Container Specification
is incubating as part of OpenSocial 2.0. It is RECOMMENDED that developers wishing to implement a Core
Gadget Container should use this incubating specification as guide for the container API.
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.One of the original goals of the OpenSocial community is to be able to constantly innovate and bring new
and exciting features into the specification. At the same time, as more and more systems deploy OpenSocial
into production, the community has a responsibility to provide a clear roadmap when new capability will be
added and, when necessary, existing capability removed.
While APIs have been deprecated in the past, there have been conventions, but no clear rules, on when
they can be removed from the specification. For example, OpenSocial 1.0 deprecated a set of JavaScript
APIs (see Appendix A). These are no longer carried forward in version 2.0. APIs MAY be deprecated by
the community in any development cycle of the specification. However, support for the APIs MUST NOT be
removed until a major version of the specification is published. The versioning scheme of the
specification itself follows the definition outlined in Core Gadget Specification.
Areas of the specification that are marked as incubating represent capability that the community would
like to standardize. Practical experience has shown that even though OpenSocial's development process
requires a prototype be used to demonstrate the implementation, there are of the specification that
have been interpreted or implemented slightly differently, resulting in less than satisfactory
interoperability. To address this, the OpenSocial community has adopted the idea of "incubating" parts
of the specification. The intent is to clearly communicate the direction of the specification and
provide a clean set of APIs and provide early adopters with a mechanism that will help achieve
interoperability. As incubating parts of the specification mature, every effort will be made not to
change the APIs. However, these APIs MAY change and are not considered under the purview of the
versioning rules of the specification.
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 publicly 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 featureExtending the social data modelsExtending the protocolThe 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” 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.
The OpenSocial specification does not provide canonical XML schema. Those provided with the
specification are for reference and illustrative purposes only. XML instance documents are not expected
to be validated and containers 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.
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.
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.
DiscussionThe "org.opensocial" is a reserved namespace for use throughout the specification. Implementors MUST NOT introduce unspecified properties of the namespace.Reserve namespace for OpenSocial constructsKey words for use in RFCs to Indicate Requirement LevelsHarvard UniversityReserved Top Level DNS NamesIBMOpenSocial Core Gadget SpecificationOpenSocial Core API Server SpecificationOpenSocial Social Gadget SpecificationOpenSocial Social API Server SpecificationOpenSocial Core Container Specification