Updated Aug 08, 2008 by mark.birbeck
Labels:	Phase-Deploy, Tutorial

GettingStartedDataRss

Getting started producing a DataRSS feed.

Introduction

DataRSS originates from Yahoo!, as part of their SearchMonkey technology. However, there is nothing proprietary about the format, since all it does is add RDFa attributes to Atom feeds.

In this tutorial we'll look at how we might create a DataRSS feed to provide metadata about job vacancies. We won't look at exactly how to set the feed itself up, since that will depend on the platform you are using. Instead we'll focus on the data that your server needs to generate.

Atom Syndication Format

If you already have an Atom feed, then the modifications you'll need to make are minor. Even if you don't currently have a feed, the chances are that the server-side software you are using supports the Atom Syndication Format.

A basic Atom feed

The first step to creating our DataRSS feed is to establish a basic Atom feed. The minimum requirements for a feed are a title and an entry to indicate when it was last updated. Let's assume that we are creating a feed to indicate available jobs with HMRC; the basic shell might look like this:

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://argot-hub.googlecode.com/svn/trunk/_samples/hmrc/datarss-assistant-officer.xml</id>
  <author>
    <name>HMRC</name>
  </author>
  <title type="text">HMRC's vacancies feed</title>
  <updated>2008-07-07T18:30:02Z</updated>

  <!-- entries will go here -->

</feed>

Note that the id element refers to the finished sample within the Argot project; you will need to change this to be your own URL.

Adding entries and adjuncts

Atom allows all sorts of information to be carried as entries in a feed. DataRSS builds on this facility by supporting adjuncts, which add additional properties about the entry that contains them.

We're going to add an entry for each vacancy that is listed on the web, and provide additional metadata about the vacancy in the form of DataRSS adjuncts.

However, since the values used to specify the properties and relationships in DataRSS are not part of Atom, a special processing instruction is used at the top of a DataRSS feed to make some new terms available:

<?xml version="1.0" encoding="UTF-8"?>
<?profile http://search.yahoo.com/searchmonkey-profile ?>
<feed xmlns="http://www.w3.org/2005/Atom">
  .
  .
  .

Also, since the adjunctcontainer and adjunct elements that we'll see in a moment are in the DataRSS namespace, we need to declare that namespace, too:

<?xml version="1.0" encoding="UTF-8"?>
<?profile http://search.yahoo.com/searchmonkey-profile ?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:y="http://search.yahoo.com/datarss/">
  .
  .
  .

Now we're ready to add some additional information.

An entry for a vacancy

Continuing the HMRC example, let's say that there is a job vacancy at the location http://www.hmrc.gov.uk/jobs/psr/deputy-head.htm; this will be the identifier for the Atom entry. We place the entry after the updated element, and include the job title:

<?xml version="1.0" encoding="UTF-8"?>
<?profile http://search.yahoo.com/searchmonkey-profile ?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:y="http://search.yahoo.com/datarss/">
  <id>http://argot-hub.googlecode.com/svn/trunk/_samples/hmrc/datarss-assistant-officer.xml</id>
  <author>
    <name>HMRC</name>
  </author>
  <title type="text">HMRC's vacancies feed</title>
  <updated>2008-07-07T18:30:02Z</updated>

  <entry>
    <id>http://www.hmrc.gov.uk/jobs/psr/assistant-officer.htm</id>
    <title type="text">Assistant Officer</title>
    <content type="application/xml">

      <!-- adjuncts will go here -->

    </content>
  </entry>

  <!-- more entries could go here, if we need them -->

</feed>

Note that we've also added the Atom content element, which is a general container for holding additional information. In it we place the DataRSS adjunctcontainer element:

  <entry>
    <id>http://www.hmrc.gov.uk/jobs/psr/assistant-officer.htm</id>
    <title type="text">Assistant Officer</title>
    <content type="application/xml">
      <y:adjunctcontainer>

        <!-- adjuncts will go here -->

      </y:adjunctcontainer>
    </content>
  </entry>

Now we're ready to add some specific information about the vacancy.

Adding information about the employer

The first adjunct we'll add contains general information about the organisation responsible for the vacancy, such as its title and a thumbnail. This information can be used by third-party applications to enhance the way information is displayed or to improve search results.

To add details about the 'employer' associated with the job vacancy, add something like this:

      <y:adjunctcontainer>
        <y:adjunct version="1.0" name="employer">
          <y:item rel="rel:Employer">
            <y:meta property="vcard:fn">HMRC</y:meta>
            <y:item rel="vcard:url" resource="http://www.hmrc.gov.uk/"/>
            <y:item rel="rel:Thumbnail" resource="http://www.hmrc.gov.uk/images/logo.gif">
              <y:meta property="media:width">160</y:meta>
              <y:meta property="media:height">62</y:meta>
            </y:item>
          </y:item>
        </y:adjunct>

The meaning of the mark-up is as follows:

rel:Employer indicates that the relationship between this adjunct and the Atom entry that contains it, is one of employer; i.e., the employer associated with the entry http://www.hmrc.gov.uk/jobs/psr/deputy-head.htm is HMRC.

vcard:fn is the full name property from the vCard vocabulary, whilst vcard:url is the URL property from the same vocabulary.

rel:Thumbnail indicates another relationship between two things, this time between the 'employer' block of data, and the information that is about to follow -- a thumbnail image of the organisation's logo.

Adding information about the vacancy

The next adjunct we'll add concerns the vacancy itself. We'll use this adjunct to provide machine-readable versions of the data that is already in the web-page for the vacancy:

        <y:adjunct version="1.0" name="vacancy">
          <y:item xmlns:v="http://code.google.com/p/argot-hub/wiki/ArgotVacancy#" rel="rel:Listing">
            <y:meta property="dc:identifier">CN-EXT-15-08</y:meta>
            <y:meta property="dc:title">Assistant Officer</y:meta>
            <y:meta property="dc:description">
              Analysing data and process applications in given timescales, liasing with customers
              and their representatives, working with colleagues to achieve team targets. In
              addition to all of the other benefits that come with working with us, you will
              enjoy 22 days annual leave, rising to 25 after a year, plus 10.5 public and privilege
              days and access to a civil service pension scheme.
            </y:meta>
            <y:meta property="geo:location">Wolverhampton</y:meta>
            <y:meta property="job:salaryType">annual</y:meta>
            <y:meta property="job:salaryFrom" datatype="currency:GBP">15262</y:meta>
            <y:meta property="job:salaryTo" datatype="currency:GBP">15262</y:meta>
            <y:meta property="job:hireType">full-time</y:meta>

            <y:meta property="v:closingDate">2008-08-08</y:meta>
          </y:item>
        </y:adjunct>
      </y:adjunctcontainer>

The rel:Listing relationship uses the 'listing' relationship from the DataRSS vocabulary, to indicate that the adjunct is actually a listing.

dc:identifier provides a unique identifier for the vacancy, dc:title indicates the job title, and dc:description is a short description of the vacancy.

geo:location provides a simple text version of the job's location.

job:salaryType indicates that the job is annual, whilst job:salarayFrom and job:salarayTo indicate the range of the salary. Whether the job is full-time or part-time is indicated by job:hireType.

Finally, the closing-date for applicants is indicated by v:closingDate.

Complete example

The complete example looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<?profile http://search.yahoo.com/searchmonkey-profile ?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:y="http://search.yahoo.com/datarss/">
  <id>http://argot-hub.googlecode.com/svn/trunk/_samples/hmrc/datarss-assistant-officer.xml</id>
  <author>
    <name>HMRC</name>
  </author>
  <title type="text">HMRC's vacancies feed</title>
  <updated>2008-07-07T18:30:02Z</updated>

  <entry>
    <id>http://www.hmrc.gov.uk/jobs/psr/assistant-officer.htm</id>
    <title type="text">Assistant Officer</title>
    <content type="application/xml">
      <y:adjunctcontainer>
        <y:adjunct version="1.0" name="employer">
          <y:item rel="rel:Employer">
            <y:meta property="vcard:fn">HMRC</y:meta>
            <y:item rel="vcard:url" resource="http://www.hmrc.gov.uk/"/>
            <y:item rel="rel:Thumbnail" resource="http://www.hmrc.gov.uk/images/logo.gif">
              <y:meta property="media:width">160</y:meta>
              <y:meta property="media:height">62</y:meta>
            </y:item>
          </y:item>
        </y:adjunct>

        <y:adjunct version="1.0" name="vacancy">
          <y:item xmlns:v="http://code.google.com/p/argot-hub/wiki/ArgotVacancy#" rel="rel:Listing">
            <y:meta property="dc:identifier">CN-EXT-15-08</y:meta>
            <y:meta property="dc:title">Assistant Officer</y:meta>
            <y:meta property="dc:description">
              Analysing data and process applications in given timescales, liasing with customers
              and their representatives, working with colleagues to achieve team targets. In
              addition to all of the other benefits that come with working with us, you will
              enjoy 22 days annual leave, rising to 25 after a year, plus 10.5 public and privilege
              days and access to a civil service pension scheme.
            </y:meta>
            <y:meta property="geo:location">Wolverhampton</y:meta>
            <y:meta property="job:salaryType">annual</y:meta>
            <y:meta property="job:salaryFrom" datatype="currency:GBP">15262</y:meta>
            <y:meta property="job:salaryTo" datatype="currency:GBP">15262</y:meta>
            <y:meta property="job:hireType">full-time</y:meta>

            <y:meta property="v:closingDate">2008-08-08</y:meta>
          </y:item>
        </y:adjunct>
      </y:adjunctcontainer>
    </content>
  </entry>
</feed>

and is available here.