[EDITING] Collections Format & Activity Streams

[James M Snell]

This particular issue has been raised before but after going through
the archive a bit I wasn't clear on the official answer...

Currently, section 2.3 of the Core Data Specification says this...

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.

Section 2.4 of the specification says this...

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.

Collection = "{"
"result : {"
[ "totalResults : " number "," ]
[ "startIndex : " number "," ]
[ "itemsPerPage : " number "," ]
[ "filtered : " ( "true" / "false" ) "," ]
[ "updatedSince : " ( "true" / "false" ) "," ]
[ "sorted : " ( "true" / "false" ) "," ]
[ "itemsPerPage : " number "," ]
"entry :" Array<Object>
"}"
"}"

Within the JSON Activity Streams format, a Collection Object is
defined as having "url", "totalItems" and "items" properties... where
the array of items is contained within the "items" property... e.g.

{
"totalItems": 10,
"items": [ ... ]
}

Obviously we have some inconsistency here, and it's a problem. For
3.0, we need to clean this up.

What I propose is that, in 3.0, we baseline on the Activity Streams
Collection Object. Meaning that within Core Data, sections 2.3 and 2.4
will be changed. When I ask for a list of items back from the server,
regardless of whether it's a collection of Activities or any other
kind of object, what we'd get back would be...

{
"totalItems" : 10,
"items": [ ... ]
}

Right now, the ONLY thing that is said about paging is the last
sentence in section 2.3, "The paging mechanism described here are
based on the OpenSearch standard with the additional requirement that
all indexes are 0 based." The challenge with this is that it's never
actually defined what this means... What I recommend is the following
convention within 3.0...

{
"$next": "http://next.page.link",
"$previous": "http://previous.page.link",
"$first": "http://first.page.link",
"$last": "http://last.page.link"
"startIndex": 0,
"itemsPerPage": 10,
"totalItems": 100,
"items": [...]
}

Each of the $ prefixed fields are links. The names identified the
relevant Link Relation Names from the IANA registry.

I would also recommend that we simply deprecate the filtered, sorted
and updatedSince extra properties defined for the Activity Streams
collection as they do not really add any real value to the base
functionality that I can determine.

- James

[Mark W.]

Would the "$" syntax conflict with any of the opensocial templating??

Also, would we be able to, once and for all, have a standard collection and paging definition b/t AS and OS?

[Laurent-Walter Goix]

clearly +1 to harmonize the parameter values with AS also for the
other service (e.g. the People Service returning POCO objects).

regarding the $next, $previous, $first, $last cannot this be already
derived by the client from startIndex, totalItems and itemsPerPage
parameters using the count and startIndex request parameters?

[James M Snell]

Yes, that's generally possible but if we can avoid requiring client
applications to construct links when they absolutely do not need to,
then all the better.

FWIW, based on recent discussion on the Activity Streams mailing list,
the Links for Activity Streams draft is being evolved such that rather
than using the ${rel} syntax (e.g. $next) the links will be grouped
under a "links" property... I hope to have an updated draft with those
changes posted shortly.

- James

> --
> You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
> To post to this group, send email to opensocial-an...@googlegroups.com.
> To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>