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.

Harvard University IBM Kaiser Permanente, for Health Level Seven Microsoft