Thursday, April 26, 2007

RSS FAQs - Atom Feed File Structure and Elements

A collection of 15 FAQs on Atom feed file structure and elements. Clear answers are provided with tutorial samples on Atom feed documents and Atom entry documents; sub-elements of the feed and entry elements; generating contents for id, updated, and link sub-elements.
Topics included in this collection are:


  1. Are Atom Feed Files XML Documents?
  2. How Many Document Types Are Defined for Atom Feed Files?
  3. What Is the Structure of Atom Feed Documents?
  4. What Are Sub-elements of the feed Element?
  5. How To Generate a Feed title Element?
  6. How To Generate a Feed subtitle Element?
  7. How To Generate a Feed link Element?
  8. How To Generate a Feed id Element?
  9. How To Generate a Feed updated Element?
  10. How To Generate a Feed author Element?
  11. What Are Sub-elements of the entry Element?
  12. How To Generate a Feed Entry link Element?
  13. How To Generate a Feed title Element?
  14. How To Generate a Feed summary Element?
  15. Can One Atom Feed Document Have Multiple Entries?


Are Atom Feed Files XML Documents?



Yes. Atom feed files are XML (eXtensible Markup Language) documents. Atom feed files
must be well-formed XML documents, respecting the following XML rules.



  • The first line must be the "xml" processing instruction with "version" and "encoding" attributes.

  • There must be only one root element in a single XML document.

  • All elements must be closed with the closing tags.

  • One element can be nested inside another element.

  • One element can not be partially nested inside another element.

  • Element attribute values must be quoted with double quotes.

  • Special characters in element attribute values or element contents must be protected using
    entities, like < and >.




How Many Document Types Are Defined for Atom Feed Files?



There are 2 document types defined for Atom feed files:



  • Atom Feed Document - Representing an Atom feed, including
    metadata about the feed, and some or all of the entries associated
    with it. Its root element is the <feed> element.

  • Atom Entry Document - Representing only one Atom entry.
    Its root element is the <entry> element.




What Is the Structure of Atom Feed Documents?



An Atom feed document must have a root element called "feed".
Within in the "feed" element, one or more "entry" elements are enclosed.
The high level structure of an Atom feed document looks like:



<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
(other feed sub-elements)
<entry>
...
</entry>
<entry>
...
</entry>
(more entry elements)
</feed>



What Are Sub-elements of the feed Element?



The "feed" element has the following sub-elements defined:



  • <author> - Specifying the personal information about an author of the contents provided in this feed.
    A feed element may have zero, one or more author sub-elements.


  • <category> - Specifying the category information of the contents provided in this feed.
    A feed element may have zero, one or more category sub-elements.


  • <contributor> - Specifying the personal information about a contributor of the contents provided in this feed.
    A feed element may have zero, one or more contributor sub-elements.


  • <generator> - Specifying the information about the software used to generate this feed.
    A feed element may have zero or one generator sub-element.


  • <icon> - Specifying the URL location of an icon image that identifies this feed.
    A feed element may have zero or one icon sub-element.


  • <logo> - Specifying the URL location of an logo image that identifies this feed.
    A feed element may have zero or one logo sub-element.


  • <id> - Specifying a URI that universally and uniquely identifies this feed.
    A feed element must exactly one id sub-element.


  • <link> - Specifying a URL location of a Web page as a reference to this feed.
    A feed element may have zero, one or more link sub-elements.
    However, at least one link sub-element with rel="self" is recommended.




  • <rights> - Specifying the information about the copyrights for this feed.
    A feed element may have zero or one rights sub-element.


  • <subtitle> - Specifying a description or a subtitle for this feed.
    A feed element may have zero or one subtitle sub-element.


  • <title> - Specifying a title for this feed.
    A feed element must have exactly one title sub-element.


  • <updated> - Specifying a time stamp of when this feed was updated.
    A feed element must have exactly one updated sub-element.


  • <entry> - Specifying an entry of a feed.
    A feed element must have one or more entry sub-elements.




How To Generate a Feed title Element?



The <title> element is a required sub-element of the <feed> element.
The title element should contain a short but human readable title of the feed document.
You should follow the same rules on Web page title elements to generate your Atom feed title elements.



One strategy is to use the same title as the Web page that your Atom feed is based on.
For example, if your Web site provides a Web page for the most popular FAQ entries for Webmasters.
That Web page has a title called: "The Most Popular FAQ Entries for Webmasters".
Now you want to generate an Atom feed for that Web page. Obviously, you should the same title as
that page:



<title>The Most Popular FAQ Entries for Webmasters</title>



How To Generate a Feed subtitle Element?



The <subtitle> element is not a required sub-element of the <feed> element.
But it is strongly recommended that you provide a subtitle element for each of your
feed documents. You should follow the same rules on Web page description meta elements
to generate your Atom feed subtitle elements.



One strategy is to use the same value of the description meta element
as the Web page that your Atom feed is based on.
For example, if your Web site provides a Web page for the most popular FAQ entries for Webmasters.
That Web page has the following description meta element:


<meta name="description" content="The top 10 popular
entries of this week on our comprehensive collection
of Webmaster FAQs."/>


Now you want to generate an Atom feed for that Web page. Obviously, you should borrow
value from the description meta element of that page:



<title>The Most Popular FAQ Entries for Webmasters</title>
<subtitle>The top 10 popular
entries of this week on our comprehensive collection
of Webmaster FAQs."</subtitle>



How To Generate a Feed link Element?



The <link> element is not a required sub-element of the <feed> element.
But it is strongly recommended that you provide a link element with rel="self" for each of your
feed documents.



The rule for feed link element is simple. It needs two attributes:



  • rel="self" - Indicating that this link is providing the URL of this feed document itself.

  • href="urlOfThisFeed" - Specifying the URL of this feed document.



For example, if you have a feed document located at http://dev.fyicenter.com/atom.xml,
you should generate a feed link element like this:



<link rel="self" href="http://dev.fyicenter.com/atom.xml"/>


The <id> element is a required sub-element of the <feed> element.
The Atom specification requires that you provide a universally unique identifier
for each of your feeds. So how to make this identifier universally unique?



One strategy is to use the URL where the feed document is located. For example,
if your Atom feed document is located at: http://dev.fyicenter.com/atom.xml,
you use the following id element in this feed document:



<id>http://dev.fyicenter.com/atom.xml</id>



How To Generate a Feed updated Element?



The <update> element is a required sub-element of the <feed> element.
The Atom specification requires that you provide a data and a time of when this feed was updated.
There is no problem to know the data and time for this element. But you need to pay attention
to the format of how the date and time should be specified.



Atom specification requires you to use the format defined in
RFC 3393 for the update element.
So you should one of the following two formats defined in RFC 3339:



  • yyyy-mm-ddThh:mm:ss.ccZ, where T is a delimiter, and Z indicates this is a UTC time value.
    For example: 2006-08-12T23:20:50.52Z.

  • yyyy-mm-ddThh:mm:ss.cczzzzz, where T is a delimiter, and zzzzz is a time zone modifier like
    -08:00, which is 8 hours behind UTC. For example: 2006-08-12T15:20:50.52-08:00.




How To Generate a Feed author Element?



The <author> element is not a required sub-element of the <feed> element.
However, it is required to have a feed author element, if one of the feed entries does not
have an author element. This requirement is to make sure that every feed entry has an author
information.



The <author> element is actually a container element, with 3 sub-elements defined as:



  • <name> - Specifying the author's name. For example: Karl King. name is a required sub-element.

  • <email> - Specifying the author's email address. For example: karl_king@fyicenter.com.
    email is not a required sub-element.

  • <uri> - Specifying the author's Web page, if exists. For example: http://www.fyicenter.com/karl_king.
    url is not a required sub-element.




What Are Sub-elements of the entry Element?



The "entry" element has the following sub-elements defined:



  • <author> - Specifying the personal information about an author of the contents provided in this feed entry.
    A feed element may have zero, one or more author sub-elements.


  • <category> - Specifying the category information of the contents provided in this feed entry.
    A feed element may have zero, one or more category sub-elements.


  • <content> - Specifying the content of this feed entry.
    A feed element may have zero, or one content sub-element.


  • <contributor> - Specifying the personal information about a contributor of the contents provided in this feed entry.
    A feed element may have zero, one or more contributor sub-elements.


  • <id> - Specifying a URI that universally and uniquely identifies this feed entry.
    A feed element must exactly one id sub-element.


  • <link> - Specifying a URL location of a Web page as a reference to this feed.
    A feed element may have zero, one or more link sub-elements.
    But if there is no content sub-element in a feed entry, at least one link sub-element with rel="alternate"
    is required.


  • <published> - Specifying a time stamp of when this feed entry was originally published
    A feed element may have zero or one published sub-element.


  • <rights> - Specifying the information about the copyrights for this feed.
    A feed element may have zero or one rights sub-element.


  • <source> - Specifying a feed entry in another feed document if this entry is a copy of that entry.
    A feed element may have zero or one source sub-element.


  • <summary> - Specifying a summary for this feed entry.
    A feed element may have zero or one summary sub-element. However it is recommended that each
    feed entry to have one summary sub-element.


  • <title> - Specifying a title for this feed.
    A feed element must have exactly one title sub-element.


  • <updated> - Specifying a time stamp of when this feed was updated.
    A feed element must have exactly one updated sub-element.



How To Generate a Feed Entry link Element?



The <link> element is not a required sub-element of the <entry> element.
But it is strongly recommended that you provide a link element with rel="alternate" for each of your
feed entries.



The rule for feed entry link element is simple. It needs two attributes:



  • rel="alternate" - Indicating that this link is providing the URL of an alternate version of
    the content of this feed entry.

  • href="urlOfTheContent" - Specifying the URL of the content of this feed entry.



For example, if you have a feed document that contains a feed entry
to represent the most popular FAQ entry of the week. Of course, that most popular
entry is a Web page with a URL like http://dev.fyicenter.com/faq/rss.
you should generate the link element for this feed entry like this:



<link rel="alternate" href="http://dev.fyicenter.com/faq/rss"/>



How To Generate a Feed title Element?



The <title> element is a required sub-element of the <entry> element.
The title element should contain a short but human readable title of the feed entry.
You should follow the same rules on Web page title elements to generate your Atom feed entry title elements.



One strategy is to use the same title as the Web page that your Atom feed entry is based on.
For example, if one of your page is included as an entry in your Atom feed document,
and that page has a title called: "Atom Feed Introduction and File Generation".
Now you want to generate an Atom feed for that Web page. Obviously, you should the same title as
that page:



<title>Atom Feed Introduction and File Generation</title>



How To Generate a Feed summary Element?



The <summary> element is not a required sub-element of the <feed> element.
But it is strongly recommended that you provide a summary element for each of your
feed entries. You should follow the same rules on Web page description meta elements
to generate your Atom feed entry summary elements.



One strategy is to use the same value of the description meta element
as the Web page that your Atom feed entry is based on.
For example, if one your FAQ page is selected as a feed entry in Atom feed document,
That Web page has the following description meta element:


<meta name="description" content="A collection of
16 FAQs on Atom feed file standard. Clear answers are
provided with tutorial samples on introduction to Atom
feed file standard; various ways to generate Atom feeds;
linking Atom feeds to Web pages."/>


You should simply borrow value from the description meta element of that page
to generate feed entry summary element:



<summary>A collection of
16 FAQs on Atom feed file standard. Clear answers are
provided with tutorial samples on introduction to Atom
feed file standard; various ways to generate Atom feeds;
linking Atom feeds to Web pages.</summary>



Can One Atom Feed Document Have Multiple Entries?



Yes. One Atom feed document can have multiple entries. Here is a good example:



<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>The Most Popular FAQ Entries for Webmasters</title>
<subtitle>The top 3 popular
entries of this week on our comprehensive collection
of Webmaster FAQs.</subtitle>
<link rel="self"
href="http://dev.fyicenter.com/faq/top_3_atom.xml"/>
<id>http://dev.fyicenter.com/faq/top_3_atom.xml</id>
<updated>2005-07-13T18:30:02Z</updated>
<author>
<name>FYIcenter.com</name>
<email>noreply@fyicenter.com</email>
</author>



<entry>
<title>Atom Feed Introduction and File Generation</title>
<link rel="alternate"
href="http://dev.fyicenter.com/faq/rss/index.html"/>
<id>href="http://dev.fyicenter.com/faq/rss/index.html</id>
<updated>2005-07-13T18:30:02Z</updated>
<summary>A collection of
16 FAQs on Atom feed file standard. Clear answers are
provided with tutorial samples on introduction to Atom
feed file standard; various ways to generate Atom feeds;
linking Atom feeds to Web pages.</summary>
</entry>
<entry>
<title>Understanding and Using Sessions in PHP Scripts
</title>
<link rel="alternate"
href="http://dev.fyicenter.com/faq/php/index.html"/>
<id>href="http://dev.fyicenter.com/faq/php/index.html</id>
<updated>2005-07-13T18:30:02Z</updated>
<summary>A collection of 19 tips on understanding and
using sessions in PHP. Clear explanations and tutorial
exercises are provided on starting and closing sessions,
saving and retrieving values in sessions, deciding how
session IDs to be transferred, deciding where to store
session files, deciding when to expire session values,
etc.</summary>
</entry>
<entry>
<title>Page Layout and Background Image Design with CSS
</title>
<link rel="alternate"
href="http://dev.fyicenter.com/faq/css/index.html"/>
<id>href="http://dev.fyicenter.com/faq/css/index.html</id>
<updated>2005-07-13T18:30:02Z</updated>
<summary>A collection of 18 FAQs/tutorials tips on
designing Web page layouts and background images.
Clear answers are provided with tutorial exercises
on screen and browser resolutions, setting Web page
width in absolute and relative length units, setting
images and font sizes in relative length units, adding
multiple background images.</summary>
</entry>
</feed>

1 comment:

Anonymous said...

Well written article.