My favorites | Sign in
Project Home Wiki
READ-ONLY: This project has been archived. For more information see this post.
Search
for
spec  
Technical specification for ProjectRSS.
Updated Oct 12, 2009 by jjb...@gmail.com

Technical specification for ProjectRSS

Authors

John Brennan

URI

http://projectrss.org/wiki/spec

Last Updated

Monday, October 12, 2009

Rights

Available under a Creative Commons License.

Description

ProjectRSS is an extension of RSS and therefore a dialect of XML. All RSS files must conform to the XML 1.0 specification, as published on the World Wide Web Consortium (W3C) website.

We break up this document into three parts -- technical fields, organizational fields, and project-specific fields.

Namespace declaration

<xmlns:projrss="http://projectrss.org/wiki/spec" />



RDF/RSS Schema definition document

Technical Fields

Element Description Required? Example Orig Spec
pubDate The publication date for the content in the channel. For example, the New York Times publishes on a daily basis, the publication date flips once every 24 hours. That's when the pubDate of the channel changes. All date-times in RSS conform to the Date and Time Specification of RFC 822, with the exception that the year may be expressed with two characters or four characters (four preferred). N Tue, 10 Jun 2003 09:41:01 GMT RSS
lastBuildDate The last time the content of the channel changed. N Tue, 10 Jun 2003 09:41:01 GMT RSS
ttl ttl stands for time to live. It's a number of minutes that indicates how long a channel can be cached before refreshing from the source. N 1440 RSS
language The language the channel is written in. This allows aggregators to group all Italian language sites, for example, on a single page.

Refer to the list of allowable values for this element. You may also use values defined by the W3C that refer to ISO 639.
N en-us RSS
generator A string indicating the program used to generate the channel. N MyActionMap.org RSS
docs A URL that points to the documentation for the format used in the RSS file. It's probably a pointer to this page. It's for people who might stumble across an RSS file on a Web server 25 years from now and wonder what it is. N http://projectrss.org/wiki/spec RSS

Organizational Fields

Element Description Required? Example Orig Spec
title Name of your organization Y Projects for Peace RSS
link The URL to the HTML website Y http://www.example.com RSS
description Phrase or sentence describing the organization Y Projects for Peace serves the local community by... RSS
foaf:Organization Several fields describing the organization, its members and its social media accounts Y More info here FOAF
image Specifies a GIF, JPEG or PNG image that is usually displayed in conjuction with the title and description of the oroganization. N More info here RSS
projrss:icon URL of a GIF, JPEG or PNG image that can be used as the custom icon for the organization's projects on the map. N http://labs.google.com/ridefinder/images/mm_20_purple.png
managingEditor Email address and name for person responsible for editorial content. N me@myorg.org (John Brennan) RSS

Deliberately, there is not a list of categories to associate with the organization at this level. ProjectRSS is based on action. Categories (e.g. taxonomy) is assigned at the project level. See Project Fields.

<foaf:Organization>

The following fields are specific to the parent <foaf:Organization> field.

Element Parent Of Description Required? Example Orig Spec
foaf:name foaf:Organization Name of your organization. This is usually the same as the title field, but serves to distinguish between multiple organizations working a project together. Y Projects for Peace FOAF
dc:type foaf:Organization A classification for the type of organization. Y More info here. Dublin Core
foaf:member foaf:Organization Contains 1 or more <foaf:Person> elements that are part of the organization. N N/A FOAF
foaf:Person foaf:member Contains 1 or more fields to describe this person N N/A FOAF
foaf:name foaf:Person Full name N John FOAF
vCard:title foaf:Person Person's title in organization N Founder vCard
vCard:email foaf:Person N someone@somewhere.com vCard
foaf:img foaf:Person URL to a photo of the person N http://example.com/john.jpg FOAF
foaf:workplaceHomepage foaf:Person URL to a bio of the person N http://example.com/bios/john FOAF
foaf:holdsAccount foaf:Organization Container for 1 or more <foaf:OnlineAccount> elements N N/A FOAF
foaf:OnlineAccount foaf:holdsAccount Contains fields describing a social media account N N/A FOAF
foaf:accountServiceHomepage foaf:OnlineAccount URL of social media homepage. May contain http and optional www. Must be the homepage and not any web page on the domain. N http://www.twitter.com FOAF
foaf:accountName foaf:OnlineAccount Account name used to identity organization on service. N worldlyjohn FOAF

Example:

    <foaf:Organization>
        <foaf:name>Organization Name</foaf:name>
        <dc:type rdf:about="http://projectrss.org/wiki/spec#Type_of_Organization">nonprofit</dc:type>
        <foaf:member>
            <foaf:Person>
                <foaf:name>John Brennan</foaf:name>
                <vCard:title>Founder, President</vCard:title>
                <vCard:email>john@my-organization.org</vCard:email>
                <foaf:img>http://www.my-organization.org/about/images/staff/john.jpg</foaf:img>
                <foaf:workplaceHomepage>http://www.my-organization.org/about/staff.htm</foaf:workplaceHomepage>
            </foaf:Person>
            <foaf:Person>
                <foaf:name>Keira Jones</foaf:name>
                <vCard:title>Director of Development</vCard:title>
                <vCard:email>keira@my-organization.org</vCard:email>
                <foaf:img>http://www.charitywater.org/about/images/staff/keira.jpg</foaf:img>
                <foaf:workplaceHomepage>http://www.my-organization.org/about/staff.htm</foaf:workplaceHomepage>
            </foaf:Person>
        </foaf:member>
        <foaf:holdsAccount>
            <foaf:OnlineAccount>
                <foaf:accountServiceHomepage>http://www.twitter.com</foaf:accountServiceHomepage>
                <foaf:accountName>worldlyjohn</foaf:accountName>
            </foaf:OnlineAccount>
            <foaf:OnlineAccount>
                <foaf:accountServiceHomepage>http://www.vimeo.com</foaf:accountServiceHomepage>
                <foaf:accountName>worldlyjohn</foaf:accountName>
            </foaf:OnlineAccount>
        </foaf:holdsAccount>
    </foaf:Organization>

Type of Organization

The attribute <dc:type> which is a children element of <foaf:Organization> defines the type of organization. It is meant to be used as a way to filter projects by the type of organization. For example, you may want to show only projects from non-profits versus projects including corporate social responsibility projects sponsored by brands.

This field can take on the following values:

  • brand
  • business
  • nonprofit
  • philanthropic

<image>

The following fields are specific to the parent <image> field.

Element Description Required? Orig Spec
url is the URL of a GIF, JPEG or PNG image that represents the channel Y RSS
title describes the image, it's used in the ALT attribute of the HTML tag when the channel is rendered in HTML Y RSS
link is the URL of the site, when the channel is rendered, the image is a link to the site. (Note, in practice the image <title> and <link> should have the same value as the channel's <title> and <link>. Y RSS

Example:

    <image>
        <url>http://s3.amazonaws.com/twitter_production/profile_images/116307986/9awaterchangeseverything_bigger.jpg</url>
        <title>Water changes everything</title>
        <link>http://</link>
    </image>

Project Fields

Element Description Required? Example Orig Spec
title Name of your project Y RSS
link The URL to the project's web page Y RSS
description Phrase or sentence describing the project Y RSS
guid A string that uniquely identifies the item. Y More info here RSS
category Includes the item in one or more categories. Y More info here RSS
georss:point A point contains a single latitude-longitude pair, separated by whitespace. Y 16.589533 5.741233 GeoRSS
georss:featurename The location of the point in human readable format. This is usually city, state and country (or city, country). N San Diego, California GeoRSS
ev:startdate The date/time when the event starts. If the ev:startdate doesn't specify timezone, then the timezone is implied in the ev:location. Time intervals are not allowed. Y 2009-11-05T08:15:30-05:00 RDF Event
ev:enddate The date/time when the event ends. If the ev:enddate is not specified it is assumed that the project is on going. Time intervals are not allowed. N 2009-11-05T08:15:30-05:00 RDF Event
ev:location The place of the event. The content is a short description. Use semantic augmentation if you desire to give i.e. a URL to the place. N San Diego, California RDF Event
projrss:point_of_contact A <foaf:Person> describing the point of contact for the project. N More info here
projrss:donatelink The URL to the organization or project specific donate page. N
projrss:funding_received Number value of total funding received for the project. Assumed currency is USD unless specified by projrss:currency property. Property values defined by ISO 4217 N 3000
projrss:funding_requested Number value of total funding requested for the project. Assumed currency is USD unless specified by projrss:currency property. N 5000
projrss:cost Number value of total project cost. Can be equal to funding requested, but may not be. Assumed currency is USD unless specified by projrss:currency property. N 10000
projrss:icon URL of a GIF, JPEG or PNG image that can be used as the custom icon for the project. This will override the <icon> element defined at the <channel> level. N http://labs.google.com/ridefinder/images/mm_20_purple.png
pubDate Indicates when the project was published. This does not have to be the same date as the project start date (and is often not the case). N Sun, 19 May 2002 15:21:36 GMT RSS
media:content References related video clips, images, and audio clips to the specific project. N More info here. Media RSS

<guid>

guid stands for globally unique identifier. It's a string that uniquely identifies the item. When present, an aggregator may choose to use this string to determine if an item is new.

<guid>http://some.server.com/project/2343</guid>

There are no rules for the syntax of a guid. Aggregators must view them as a string. It's up to the source of the feed to establish the uniqueness of the string.

If the guid element has an attribute named "isPermaLink" with a value of true, the reader may assume that it is a permalink to the item, that is, a url that can be opened in a Web browser, that points to the full item described by the <item> element. An example:

<guid isPermaLink="true">http://inessential.com/2002/09/01.php#a2</guid>

isPermaLink is optional, its default value is true. If its value is false, the guid may not be assumed to be a url, or a url to anything in particular.

<projrss:point_of_contact>

The following fields are specific to the parent <foaf:Organization> field.

Example #1 - Embed an image:

    <foaf:Person>
        <foaf:name>John Brennan</foaf:name>
        <vCard:title>Founder, President</vCard:title>
        <vCard:email>john@my-organization.org</vCard:email>
        <foaf:img>http://www.my-organization.org/about/images/staff/john.jpg</foaf:img>
        <foaf:workplaceHomepage>http://www.my-organization.org/about/staff.htm</foaf:workplaceHomepage>
    </foaf:Person>

<category>

<category> is a required sub-element of <item>.

It has one optional attribute, domain, a string that identifies a categorization taxonomy.

The value of the element is a forward-slash-separated string that identifies a hierarchic location in the indicated taxonomy. Processors may establish conventions for the interpretation of categories. An example is provided below:

<category domain="http://projectrss.org/wiki/open-philanthropy#Taxonomy">water</category>

Specific to philanthropy, a taxonomy is emerging here.

<media:content>

The following fields are specific to the parent <media:content> field. See the Media RSS Module for all attributes.

Example #1 - Embed an image:

    <media:content url="http://my-organization.org/completed/project1.jpg" type="image/jpeg" medium="image" >
        <media:title type="plain">Day #2</media:title>
        <media:description type="plain">We're just beginning...</media:description>
        <media:thumbnail url="http://my-organization.org/completed/project1_sm.jpg" width="75" height="50" />
        <media:copyright url="http://my-organization.org/additional-info.html">2009 MyOrg</media:copyright>
    </media:content>

Example #2 - Embed a (YouTube) video:

    <media:content medium="video">
        <media:player url="http://youtube.com/?v=XXXXXXXXXXX" /> 
        <media:thumbnail url="http://i1.ytimg.com/vi/XXXXXXXXXXX/default.jpg" width="120" height="90" /> 
        <media:title>Digging a well</media:title>
        <media:credit>John Brennan</media:credit> 
        <enclosure url="http://youtube.com/v/XXXXXXXXXXX.swf" duration="155" type="application/x-shockwave-flash"/> 
    </media:content>

where XXXXXXXXXXX is the video id.

Examples

Please refer to the Examples page.

Open Issues

This specification is still a work in progress. While fields already defined will remain in the final draft, there remains other fields used to describe most projects that do not yet exist in this spec. If there are general fields you don't see, please leave it in the comments.

Currently we are still working out the following:

  • How to define when multiple organizations are working on a project together?

Specification Notes

  • While the FOAF Spec states that elements like <foaf:accountServiceHomepage> should have the following format:

<foaf:accountServiceHomepage rdf:resource="http://www.account-service.com"/>
This makes the feed as a whole invalid with some RSS parsers. Furthermore, parts of the spec are still considered unstable. Since the goal of ProjectRSS is to be compatible with RSS Readers, we will describe these elements like the following:
<foaf:accountServiceHomepage>http://www.account-service.com</foaf:accountServiceHomepage>

Comment by fineartd...@gmail.com, Aug 11, 2009

One issue which I had considered was differentiating between the place where an event occurs, and the place which will benefit.

For example, a lemonade stall could have a location on my street, but it will also have a location where the money raised will be used to build a well.

I can see both being useful for people searching for opportunities to do goo things.

Comment by project member jjb...@gmail.com, Aug 13, 2009

@findartdavid: That's a great point! Although it starts to get complicated when you can have many lemonade stands (e.g. fundraisers) contributing to the same benefit project. And does it benefit a project you are also working on or is it another organization?

Perhaps the right way is almost 2 separate feeds (assuming you are not the same organization that will do the work in the field)

  1. ProjectRSS feed for all your fundraising efforts (lemonade stand benefiting organization X). This could also be tied into an individual "actions" feed for yourself to display on a map.
2) ProjectRSS feed for the organization you are helping out. They would show the project that the fundraising money contributed too.

And of course some sort of linking between your fundraiser and the organization. But we'd need a common identifier for you both. And it shouldn't be owned by any 1 site. Perhaps a URI?

Thoughts?

And thanks for the feedback!!

Comment by kester.e...@gmail.com, Apr 9, 2010

Also re georss. I'm implementing this for http://nabuur.com/ a point is fine for projects for their 'villages' - online projects for a place somewhere in the world. It, however, makes no sense for projects for their 'groups' - which are online groups with online projects. Yet the point is required.

Powered by Google Project Hosting