OpenSocial Core Data Specification 2.5.1
opensocial-and-gadgets-spec@googlegroups.com
This document defines all the data objects used in the and specifications.
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.
Domain name examples use
RFC2606.
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 =
]]>
An Array is represented as a comma separated list of values, surrounded by square brackets.
Array<Object> = "[" #Object "]"
Boolean = "true" / "false"
Many service operations return a list of OpenSocial resources. Lists are
always returned in the "list" field of the result. Lists can either be the
full set of resources or a pageable subset. If the operation supports
random access indexing of the full list it will support the "startIndex"
and "count" parameters which control what sublist of the full list is
returned. The paging mechanisms described here are based on the OpenSearch
standard with the additional requirement that all indexes are 0 based.
The Collection data type will have metadata information that provides information
about the data returned.
Collection = "{"
"result : {"
[ "totalResults : " number "," ]
[ "startIndex : " number "," ]
[ "itemsPerPage : " number "," ]
[ "filtered : " ( "true" / "false" ) "," ]
[ "updatedSince : " ( "true" / "false" ) "," ]
[ "sorted : " ( "true" / "false" ) "," ]
[ "itemsPerPage : " number "," ]
"list :" Array<Object>
"}"
"}"
Field Name
Field Type
Description
startIndex
number
The index of the first result returned in this response,
relative to the starting index of all results that would be returned if
no startIndex had been requested. In general, this will be equal to the
value requested by the startIndex, or 0 if no specific startIndex was
requested.
itemsPerPage
number
The number of results returned per page in this response.
In general, this will be equal to the count Query Parameter,
but MAY be less if the Service Provider is unwilling to return as many
results per page as requested, or if there are less than the requested
number of results left to return when starting at the current startIndex.
totalResults
number
The total number of data that would be returned if
there were no startIndex or count specified. This value tells the
Consumer how many total results to expect, regardless of the current
pagination being used, but taking into account the current filtering
options in the request.
list
Array<Object>
An array of objects, one for each item matching the request.
For consistency of parsing, if the
request could possibly return multiple items (as is normally the case),
this value MUST always be an array of results, even if there
happens to be
0 or 1 matching results. (i.e. "list": [ { /* first item */ },
{ /* seond item */ } ]).
filtered
Boolean
indicating if the result honors filter params in the
request. The default value is 'true' if the field does not
exist.
sorted
Boolean
Indicating if the items are sorted. The default value is
'true' if the field does not exist.
updatedSince
Boolean
Indicating if the result honors the updatedSince param in
the request. The default value is 'true' if the field does not
exist.
Discussion
Discussion
OpenSocial 2.0 has incorporated support for the Activity Streams community specification. This specification
also defines a collection structure. In order to maintain compatibility with endpoints that expect an
Activity Streams collection definition, OpenSocial containers SHOULD append the additional fields onto
collection structures that are returned from the ActivityStreams service.
Note: The OpenSocial specification declares that extensions should be wrapped in "tags" that "namespace" the
extended fields. This is done primarily to avoid collisions. However, an endpoint that is configured to
receive an Activity Stream collection would not expect collection fields to be wrapped. Therefore, in order
to support interoperability, an exception has been made for OpenSocial Collection. Fields from Activity
Streams Collection SHOULD be appended directly to OpenSocial Collection.
See: XML Schema dateTime format
Example: 2008-01-23T04:56:22Z
See: XML Schema dateTime format, offset portion
Example: -08:00
The Domain-Name is an optional data type that containers may
use to uniquely identify themselves. It is recommended that they
use a registered domain name where possible.
Domain-Name = *( ALPHA / DIGIT / "_" / "." / "-" )
The Global-Id is an optional data type designed to allow
scoping of ids across domains. Global-Ids are identified by
containing a semi-colon (:) as part of the id itself. If a
containers supports the Global-Id, all API calls MUST support the
Global-Id for queries, the returned data may optionally use
Global-Ids. It is the responsibility of the consumer to verify
the type of returned Id is appropriate for their usage, and to
convert any Local-Ids to Global-Ids as needed.
Global-Id = Domain-Name ":" Local-Id
Discussion
There are several external systems and specifications that leverage the use of IRI as the way to uniquely and
globally identify an object. Activity Streams is an example of one such specification. OpenSocial's uses a
slightly different format for uniquely identifying objects. To support interoperability with other containers
as well as Activity Stream endpoints, OpenSocial 2.0 introduces an alternate format for uniquely identifying
its objects that is based upon the IRI scheme.
IRI is an acronym for "Internationalized Resource Identifier". It has a structure similar to a URL. From the
perspective of OpenSocial, the objective is to easily map the components of Global Id into an IRI that may be
used to access the resource, e.g. via REST endpoints. To create an IRI, the following pattern should be used:
Global Id will map to the IRI iauthority.
Local Id will include an IRI ipath-absolute that represents the OpenSocial service, plus an IRI ipath-rootless
that contains the Local-Id.
An example of this mapping is as follows. Let's assume that we have an OpenSocial based container named
"MySocial". It's domain is "MySocial.com". Each user is given a unique user Id, e.g. 1234. The OpenSocial
Object Id is: MySocial.com:1234
To construct an IRI from the Global Id using the mapping above, the result would be:
https://MySocial.com/people/1234
IRI that are created MUST conform to the patterns defined in the OpenSocial Core API Server specification. It
is RECOMMENDED that they conform to Section 2.1, REST. The ipath-absolute SHOULD be an OpenSocial service as
defined in the Social API Server specification. However, this is not mandated because it is the intent that the
programming model defined by this specification be extended. Therefore, new services may be added outside of a
specification cycle, e.g. incubating, or as a domain specific service. In the situation where a service is use
that is NOT defined by the OpenSocial specification, it is RECOMMENDED that a definition of that service be
publicly available via the Internet. Where an IRI is used in the specification, as in the Activity Streams,
containers MUST support this alternate form of Global ID. Containers SHOULD use this alternate form of Global
ID as a replacement for Global ID.
Readers of this section should also review the Security section in the
Core API Server specification as well as the OAuth information
documented in the Core Gadget Specfication. The reader should also
be familiar with the OAuth specification (1.0A or 2.0).
Discussion
The parameters described in this section are set by the gadget running in
the Core Container and are passed
to the Core Gadget Server so that it will appropriately process the request.
If a gadget is using a Core Gadget Server to proxy requests to a remote server
then none of the OAuth parmeters documented here are necessary and they
should not be used.
The http parmaeters for OAuth documented here are used in cases where
a gadget is running in Javascript only (or similar) environments
(called an implicit grant in OAuth speak). In these scenarios, a gadget does
not have a Core Gadget Server that stores token information. In these
scenarios, a gadget talks directly to the remote server it wants to obtain
data from. When operating in a Javascript only environment, or those with
similar characteristics, some of the documented request parameters
will be needed.
Requests to arbitrary URLs use the following parameters:
Name
Type
Description
alias
String
The external service name, defined by the application developer, as part of the module preferences. This
will indicated to the container which external service tag to use. Discussion
authz
String
Indicates the authorization method to use when sending data to the remote server.
Must be one of "none", "signed", "oauth" or "oauth2". Defaults to "none". Discussion
format
String
Format data is returned in for processing, values are "json" or "text". Defaults to "json". Optional
headers
Map<String, Array<String>>
Additional HTTP headers to include in the request. Optional.
href
String
The URL to send the request to. Required.
oauth_service_name
String
Gadget XML can define more than one "clause" that represents an end point protected by OAuth
that the gadget accesses.
This parameter identifies the "service element" or "xml nickname" in the gadget XML
that identifies the OAuth information to be used for this specific request.
Defaults to an empty string.
** Not sure when this would ever be used. In proxied requests, this is unnecessary
because the information about a service element is passed on the makeRequest call.
In a Javascript-like environment, the gadget will not refer to its own XML specification
but will simply supply the correct token and URI. This parameter is optional.
oauth_request_token
String
This parameter uses OAuth 1.0a terminology but is also used for OAuth 2 scenarios.
This is an access token that is pre-approved by the provider for access to the
resource. When calls are proxied by the Core Gadget Server, the gadget should not
have direct access to oauth tokens so this parameter will not be used.
This parmaeter is optional.
oauth_request_token_secret
String
Secret associated with the pre-approved request token. This parameter
is left here for legacy reasons and MUST never be used. Gadgets cannot
secure secrets in the browser and therefore should never hold secrets.
The OAuth 2 security considerations clearly outline that for browser
based software, secrets should not be issued. For proxied requests,
the secrets are held by the Core Gadget Server and are passed by
the server on the proxied call. This parmaeter is optional.
oauth_token_name
String
Identifies the OAuth token used to make a request to the service provider. Defaults to an empty string.
For proxied requests, the token name is passed in the optional parameters to the makeRequest API call
so this parameter is unnecessary.
** Not sure when this would ever be used. In a Javascript only situation, a gadget won't need
to use the indirection associated with passing a token name, but will pass the access token
directly on the call.
oauth_use_token
String
Controls whether an OAuth token should be used with the request.
Allowed values are "always", "if_available", and "never". This parameter is optional.
**Not sure why this would ever be used. If other OAuth parameters are passed and if
the authz parameter is set to "oauth" or "oauth2" then it is clear that OAuth should be used.
If those other parmeters are missing, then OAuth won't be used.'
refreshInterval
number
Number of seconds for which the container can cache the data. If this parameter is set, it overrides the HTTP response header sent back from the HTTP request. Optional.
sign_owner
Boolean
Indicates if the current viewer's ID should be included in the request signature. Defaults to "true".
sign_viewer
Boolean
Indicates if the current viewer's ID should be included in the request signature. Defaults to "true".
When a container makes an HTTP request on behalf of a gadget (e.g. osapi.http.get(), or <os:HttpRequest>) the response will contain the following properties:
Name
Type
Description
content
String / Object
If @format is "text", the string content of the
response. If @format is "json", the parsed JSON object or array of the
response. If a JSON response cannot be parsed, a 406 (Not Acceptable) error
code will be produced.
headers
Map<String, Array<String>>
An map with response header names as keys,
and the header values as per-key arrays.
status
number
The HTTP status code.
Local-Id = *( ALPHA / DIGIT / "_" / "." / "-" )
Object-Id is to be an opaque string value that the API will
use for resultant data and for queries. Containers MUST support
for any query, and valid id that the API returns. Containers MAY
support the Global-Id format.
Object-Id = Local-Id / Global-Id
Field Name
Field Type
Description
value
Object
The primary value of this field, e.g. the actual e-mail address, phone
number, or URL. When specifying a sortBy field in the Query Parameters for
a Plural Field, the default meaning is to sort based on this value
sub-field. Each non-empty Plural Field value MUST contain at least the
value sub-field, but all other sub-fields are optional.
type
string
The type of field for this instance, usually used to label the
preferred function of the given contact information. Unless otherwise
specified, this string value specifies Canonical Values of work, home,
and other.
primary
Boolean
A Boolean value indicating whether this instance of the Plural Field
is the primary or preferred value of for this field, e.g. the preferred
mailing address or primary e-mail address. Service Providers MUST NOT
mark more than one instance of the same Plural Field as primary="true",
and MAY choose not to mark any fields as primary, if this information is
not available. For efficiency, Service Providers SHOULD NOT mark all
non-primary fields with primary="false", but should instead omit this
sub-field for all non-primary instances.
label
String
Provides a human-readable, plain-text, and preferrably localized short description of the object value suitable for display to a user.
When returning Plural Fields, Service Providers SHOULD canonicalize the
value returned, if appropriate (e.g. for e-mail addresses and URLs).
Providers MAY return the same value more than once with different types
(e.g. the same e-mail address may used for work and home), but SHOULD NOT
return the same (type, value) combination more than once per Plural Field,
as this complicates processing by the Consumer.
A User-Id uses the same format as an Object-Id, but there are several reserved values for common cases.
User-Id = Object-Id / "@owner" / "@viewer" / "@me"
The reserved values are defined in the following table:
Value
Description
@owner
The user that owns the current page. For example, if Alice is viewing Bob's profile page, then Bob is the owner.
@viewer
The user than is logged in an viewing the current page. For example, if Alice is viewing Bob's profile page, then Alice is the viewer.
@me
The currently authenticated user. For example, when an API request is received the user who's credentials are included in the authorization header of the request can be referenced as '@me'.
Support for the ATOM format is being deprecated in the OpenSocial 2.0 release. Consumers should start migrating to using JSON or XML representations.
Each resource has three representations, as JSON, XML, and Atom. All data
must be representable in each format. The XML and JSON formats have a one to
one mapping while the Atom format is defined separately for each type of
object and collection. Throughout this document, examples are only given
in JSON and Atom. The XML representation can be mapped directly from the
JSON and MUST conform to the XSD provided for each data type.
Each resource is represented as a hierarchical tree of elements. Ordering
of elements within a parent element may or may not be significant, depending
on the context. Mapping consists of converting between the internal
hierarchy and the JSON/XML or Atom protocol format.
The general rules for mapping between the Atom and JSON formats are as
follows. Each data type may add additional aliasing rules.
The default location for all data in the Atom format is in
atom:entry/atom:content/datatype, where datatype is a root node naming the
type of data delivered: <person>, <group>, <activity>, or
<appdata>.
The field names are specified at the end of this document in
camelCase.
Strings are represented as strings in both formats.
Dates and timestamps are represented as strings using
RFC3339 Timestamps format date-time elements.
These are also known as "XSD Dates". In cases where only a day-of-the-year
is desired, e.g., a birthday, the year SHOULD be specified as 0000.
Enums are represented as objects with "displayvalue" (localizable,
customizable string) and "key" (key) fields.
Arrays are represented as arrays in the JSON representation and as
repeated fields in the XML representation.
Sub-objects are represented as sub-elements in both formats.
Fields are placed directly in the root object in the JSON format. In the
Atom format, they are by default placed under atom:content/datatype (e.g.,
atom:content/person for person data). Some fields are 'hoisted' and aliased
to standard Atom fields directly underneath atom:entry. There are three
standard aliases that apply to all data types:
atom:entry/atom:id aliases the "id" field. The JSON format id is the
OpenSocial globally unique ID, which consists of the container domain
(e.g., example.org) followed by a colon and the container's id for that
person. The container specific id can only contain letters (A-Za-z),
numbers (0-9), dots (.), hyphens (-) and underscores (_). For example,
example.org:78gh37261ddfdf. In the Atom format, it is translated into the
required URI data type by prepending "urn:guid:" to the OpenSocial ID
string. These rules are intended to make mapping IDs between the RESTful
API and the JS API straightforward while preserving global uniqueness.
atom:entry/atom:updated aliases the JSON field indicating the most
recent update time if available (POSTED_TIME for Activity), or the
generation time if no better information is available.
atom:entry/atom:published aliases the JSON field indicating creation
time (POSTED_TIME for Activity).
Singular fields are encoded as string key/value pairs in JSON and tags
with text content in XML, e.g. "field": "value" and
<field>value</field> respectively.
Plural fields are encoded as arrays in JSON and repeated tags in XML,
e.g. "fields": [ "value1", "value2" ] and
<field>value1</field><field>value2</field>
respectively.
Nodes with multiple sub-nodes are represented as objects in JSON and tags
with sub-tags in XML, e.g. "field": { "subfield1": "value1", "subfield2":
"value2" } and
<field><subfield1>value1</subfield1><subfield2>value2</subfield2></field>
respectively.
Incorporate ActivityStreams 1.0 into OpenSocial
Add 'alias' to HTTP Request
OAuth 2.0 Support
Missing the specifications for metadata information for Collections data type for JSON-RPC and REST endpoints
Key words for use in RFCs to Indicate Requirement Levels
Harvard University
Reserved Top Level DNS Names
IBM
Augmented BNF for Syntax Specifications: ABNF
Date and Time on the Internet: Timestamps
ASCII format for Network Interchange
XML Schema Part 2: Datatypes Second Edition
Kaiser Permanente, for Health Level Seven
Microsoft
OpenSocial Core Gadget Specification
OpenSocial Core API Server Specification