Cosmo Feed Service: Collections and Items

Collections

See CosmoFeedCollections.

Items

See CosmoFeedItems.

Projections

The concept of projection is taken from GData. It defines the amount and type of data that is returned in an Atom document, how the entries are ordered in a feed, etc. Some projections are useful for both feeds and entries, but some projections are only meaningful when applied to feeds.

A client chooses a specific projection for a feed or entry by including a projection identifier in the URI. See CosmoFeedCollections and CosmoFeedItems for how to construct feed and entry URIs containing projection identifiers.

Basic

A feed with the basic projection contains an inline human-readable content and summary for every note item in the collection ordered with the entry for the most recently updated item first. This projection is also valid for entries.

Feeds and entries with this projection are intended for read-only consumption by feed readers and aggregators. The content of a basic entry is HTML in the hCalendar microformat. The summary of a basic entry is text. The author element of feed and entry documents does not include the entry point URI of the owner of the collection or item, as the entry point URI does not provide useful data for this type of client. Basic entry documents do not provide edit links.

In addition to any other links, a basic collection feed provides a link with rel pim and type text/html which refers to the "bookmarkable" web view of the collection.

The feed service honors time-range query parameters specified in a feed URI with the basic projection as well as the tz query parameter (see Queries). Unlike other projections, basic feeds do not contain an entry for the master recurring item itself.

Full

A feed with the full projection contains an exhaustive amount of machine-processable data for every note item in the collection ordered with the entry for the most recently updated item first. This projection is also valid for entries.

Feeds and entries with this projection are intended for use by clients that manipulate server data, such as the Cosmo web UI. The content of a full entry is a complete representation of an item in one of the data formats described elsewhere in this document.

Full entry documents provide the following additional links:

• rel parent for each collection of which the item is a member
• rel modifies if the item is a modification of another item
• rel modification for each modification of the item
• rel expanded if the item is recurring, providing the URI for an expanded feed for the item (see CosmoFeedItems)
• rel master if the entry represents a "regular" (i.e. non-modification) occurrence of a recurring item
• rel edit if the entry represents a master or modification item

The feed service honors time-range query parameters specified in a feed URI with the full projection as well as the tz query parameter (see Queries).

Dashboard

Dashboard feeds behave much like full feeds except that the member items represented by the feed are limited to those of a certain triage status (explicit or implied). The feed service actually supports three related dashboard projections, one for each possible triage status.

The feed service ignores any time-range query parameters specified in a feed URI with the dashboard projection. It does, however, honor the tz query parameter (see Queries).

Now

A feed with the projection dashboard-now includes entries for the following items:

• all untriaged items
• single-occurrence items and modifications explicitly triaged NOW
• modifications and occurrences whose period overlaps the current point in time

The entries in this feed are sorted in chronological order.

Later

A feed with the projection dashboard-now includes entries for the following items:

• single-occurrence items explicitly triaged LATER
• either the next occurring modification explicitly triaged LATER or the next occurrence, whichever occurs sooner

The entries in this feed are sorted in reverse chronological order.

Done

A feed with the projection dashboard-done includes entries for the following items:

• single-occurrence items explicitly triaged DONE
• either the most recently occurring modification explicitly triaged DONE or the most recent occurrence, whichever occurred more recently

The entries in this feed are sorted in chronological order.

Details

A feed with the details projection contains extra information about a collection but does not contain any entries. This allows clients to get certain details about the collection without forcing the feed service to compute entries for each item in the collection. This projection is only valid for collections.

Feeds with this projection are intended for use by clients that manipulate server data, such as the Cosmo web UI.

Details feed documents provide the following additional links:

• rel edit which can be used to update the collection (see CosmoFeedCollections)
• rel morse code which can be used to access the collection with Morse Code
• rel dav which can be used to access the collection with WebDAV and related protocols
• rel webcal which can be used to access an aggregate iCalendar representation of the collection's members
• rel pim which refers to the "bookmarkable" web view of the collection

Additionally, the feed document contains an extension element for each ticket granted on the collection that is visible to the requesting principal.

namespace cosmo = http://osafoundation.org/cosmo/Atom

cosmoTicket =
  element cosmo:ticket {
    attribute type { "read-only" | "read-write" | "free-busy" },
    text // the ticket key
  }

Data Formats

A client chooses a specific data format for a feed or entry by including a format identifier in the URI.

For most projections, the feed service translates items into EIM record sets and represents them in either JSON or XML (in the future, the feed service may also support additional representations such as iCalendar, xCal and RDF Calendar). For these feeds, a client chooses a specific format by including a format identifier in the URI. See CosmoFeedCollections and CosmoFeedItems for how to construct feed and entry URIs containing format identifiers. If a format identifier is not provided in the URI, the feed service returns EIM-JSON representations.

For the basic projection, the feed service represents items with HTML and the hCalendar microformat. It does not accept entry content from clients in this format.

EIM-JSON

The URI identifier for EIM-JSON is eim-json, and the media type is application/eim+json. Find more information at EimJsonSpec.

EIMML

The URI identifier for EIMML (the XML encoding of EIM) is eimml, and the media type is application/eim+xml. Find more information at EimmlSpec.

Queries

A feed URL's query string can be used to make a parameterized feed query. The feed service recognizes the following query parameters:

start

the RFC 3339 date-time that specifies the earliest end time for event items to be returned; must be specified along with end

end

the RFC 3339 date-time that specifies the latest start time for event items to be returned; must be specified along with start

tz

the Olson identifier (e.g. America/Los_Angeles, PST) for the timezone used to resolve floating start and end times

Time-Range Query

A time-range query (one that includes start and end) performs recurrence expansion over the given time range. The resulting collection feed or expanded item feed includes entries for all single-occurrence items that overlap the time range and all recurring item occurrences (including modifications) that overlap the time range. For all projections other than basic, the feed also includes an entry for each master recurring item for which at least one occurrence is included.

Floating Date-Time Resolution

If a timezone identifier (tz) is provided, it is used to resolve floating start and end times. If none is provided, floating times are resolved relative to the server's default timezone.