R3S Specifications
Really Simple Semantic Syndication (R3S) is a specification designed by Weever Apps for generating relevant data from any kind of web object. This could include a blog, a web page, a category of content in a CMS, geo-tagged content, and so on.
It is different than RSS in that it:
- is in JSON format
- delivers only relevant information
- can deliver any content, not just recent content
- can deliver a static web pages' content or data
- tends to have a smaller data and bandwidth footprint
We have designed R3S for potential uses other than generating mobile apps: specifically, for introducing a standard by which any CMS could create an API for connecting to its content. This means there are parts of the specification that are not used by our API, but are there for either future use or use in other contexts.
For those looking to add your CMS Extension's R3S feed to a standard tab, please see Adding an R3S Feed from Joomla or WordPress.
Contents |
Channel Feeds
An R3S channel only delivers metadata related to a particular query. A Weever mobile app would then re-request details about a particular object once it is determined by the user what exact content they wish to browse.
Channel Definitions
An R3S channel is a collection of content items, similar in concept to an RSS feed. There are two important aspects: the channel's main Data Feed which includes all the data about the feed itself, and the channel Feed Items which contain summary data about each content item.
Channel Data Feed
The main Data Feed for a channel contains properties relating to the channel as a whole. This includes the type of content in the channel, version data, and additional metadata. Note that some properties are currently unimplemented in Weever Apps, but are reserved for future use.
| Type | Description | Use | |
|---|---|---|---|
| name | string
|
Name of feed source (blog name, gallery name, etc) | Recommended |
| items | items object
|
An object containing the channel content item summaries (see below at "Channel Feed Items") | Required |
| type | contentType
|
What kind of content is being returned (html, media, etc) | Required |
| r3sVersion | string
|
Specification version being used | Required |
| generator | string
|
Component or library outputting this content [IE, "R3S 0.8.1 for Joomla 1.7, release version 1.3.1"] | Required |
| url | url
|
Site URL | Recommended |
| thisPage | int
|
Pagination, which page of data is being requested (default: 1) | Recommended |
| lastPage | int
|
Pagination, last possible page (default: 1) | Recommended |
| count | int
|
How many items are being returned | Required |
| sort | sortType
|
How the items are sorted (alphabetic, most recent, etc) | Unused |
| geo | geo object
|
Geolocational data related to whole channel. Note: All requests that Weever Apps makes that expect GPS data to be included will include the query parameter "geotag=true". This way you can avoid any GPS calculations in circumstances where they will not be used. | Unused in Data Feed |
| description | string
|
Summary description of content being delivered | Unused |
| language | [RFC 5646]
|
Localization of the content ("en-US", etc) | Unused |
| copyright | string
|
Copyright statement for the content | Unused |
| license | string
|
Any licensing pertaining to the content (Creative Commons, GPL, etc) | Unused |
| publisher | string
|
Name of website owner/company | Unused |
| rating | string
|
Like RSS rating attribute, generally used for flagging mature or offensive content | Unused |
| relationships | relationships object
|
An object containing context-relevant semantic data | Unused |
Channel Feed Items
Each channel feed item represents a content item, similar to an article contained inside an RSS feed. The item properties however, only contain summary information. The purpose for this is to minimize data footprint, to wait for the end-user to indicate which content item they would like to read. Once they request a particular content item, a request for a Details item is made.
| Type | Description | Use | |
|---|---|---|---|
| name | string
|
Name of content (article title, file name, etc) | Required |
| url | url
|
URL of item | Required |
| type | contentType
|
What kind of content is being returned (htmlContent, media, event, profile, tableData, inputRequest) | Required |
| image | image object
|
URL for mobile(optional) and normal resolution | Recommended |
| geo | geo object
|
Geolocational data related to item. Note: All requests that Weever Apps makes that expect GPS data to be included will include the query parameter "geotag=true". This way you can avoid any GPS calculations in circumstances where they will not be used. | When Relevant |
| r3sVersion | string
|
Specification version being used | Required |
| generator | string
|
Component or library outputting this content [IE, "R3S 0.8.1 for Joomla 1.7, release version 1.3.1"] | Required |
| author | string
|
Name of the content author | Recommended |
| datetime | itemDatetime object
|
Datetimes for published, modified (and start/end for event items) | Recommended |
| tags | itemTags array
|
Taxonomical tags array | Recommended |
| description | string
|
Summary of content; could include traditional "read more" introtext, partial content, or a brief abstract of content. | Unused, implementation in testing |
| publisher | string
|
Name of (original) publisher, used if aggregated content | Unused |
| uuid | string
|
Unique Universal Identifier (should be unique; urls could change whereas this would remain the same) | Unused |
| relationships | relationships object
|
An object containing context-relevant semantic data | Unused |
Details Feeds
An R3S details feed delivers full access to a specific content object.
Feed format note
All R3S details feeds need to be encapsulated in a "results" object. For example:
"results": { /* R3S details result feed */ }
details::htmlContent
An htmlContent details feed contains both HTML and metadata information about a web page, article, or content item. This is used to display a whole article to the end-user.
| Type | Description | Use | |
|---|---|---|---|
| html | html
|
String containing HTML content | Required |
| url | url
|
URL of item | Required |
| geo | geo array
|
Geolocational data related to item. Note: All requests that Weever Apps makes that expect GPS data to be included will include the query parameter "geotag=true". This way you can avoid any GPS calculations in circumstances where they will not be used. | When Relevant |
| r3sVersion | string
|
Specification version being used | Required |
| generator | string
|
Component or library outputting this content [IE, "R3S 0.8.1 for Joomla 1.7, release version 1.3.1"] | Required |
| author | string
|
Name of the content author | Recommended |
| datetime | htmlDatetime object
|
Datetimes for published, modified | Required |
| tags | itemTags array
|
Taxonomical tags array | Recommended |
| publisher | string
|
Name of (original) publisher, used if aggregated content | Unused |
| copyright | string
|
Copyright statement for the content | Unused |
| license | string
|
Any licensing pertaining to the content (Creative Commons, GPL, etc) | Unused |
| uuid | string
|
Unique Universal Identifier (should be unique; urls could change whereas this would remain the same) | Unused |
| relationships | relationships object
|
An object containing context-relevant semantic data | Unused |
Other Details Feeds
Other feed types' support is forthcoming.
R3S Feed Examples
Here's are some sample URLs using the specifications:
