OpenSocial Core Data Specification 1.1

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. Collection = "{" "result : {" [ "totalResults : " number "," ] [ "startIndex : " number "," ] [ "itemsPerPage : " number "," ] [ "filtered : " ( "true" / "false" ) "," ] [ "updatedSince : " ( "true" / "false" ) "," ] [ "sorted : " ( "true" / "false" ) "," ] [ "itemsPerPage : " number "," ] "entry :" 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. This field MUST be present if and only if a value for count is specified in the request. totalResults number The total number of contacts 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. entry 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. "entry": [ { /* 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.

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

Requests to arbitrary URLs use the following parameters: Name Type Description authz String Indicates the authorization method to use when sending data to the remote server. Must be one of "none", "signed", or "oauth". Defaults to "none". 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 Identifies the service element in the gadget spec to use for this request. Defaults to an empty string. oauth_request_token String A token that is pre-approved by the provider for access to the resource. Optional. oauth_request_token_secret String Secret associated with the pre-approved request token. Optional. oauth_token_name String Identifies the OAuth token used to make a request to the service provider. Defaults to an empty string. oauth_use_token String Controls whether an OAuth token should be used with the request. Allowed values are "always", "if_available", and "never". Optional. 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. 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'.

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.