AtomEnabled

Atom Syndication Format - Introduction

Developers >=20 Syndication

Wh= at is=20 Atom?=20
- About=20 this document=20
- Sa= mple=20 feed
Feed Elements=20
- Required=20
- Recommended=20
- Optional=20
Entry Elements=20
- Required=20
- Recommended=20
- Optional=20
Common Constructs=20
- Cate= gory=20
- Content=20
- Link= =20
- Person= =20
- Text= =20
Extending=20 Atom=20
See=20 Also

What is Atom?

Atom is the name of an XML-based Web content and metadata syndication = format,=20 and an application-level protocol for publishing and editing Web = resources=20 belonging to periodically updated websites.

All Atom feeds must be well-formed XML documents, and are = identified with=20 the application/atom+xml media type.

About this document

This document focuses on The=20 Atom Syndication Format produced by the IETF AtomPub = Working=20 Group. In the event that this document differs from the Internet = Draft, the=20 Internet Draft is to be considered authoritative.

General considerations:

All elements described in this document must be in the http://www.w3.org/2005/Atom = namespace.=20
All timestamps in Atom must conform to RFC 3339.=20
Unless otherwise specified, all values must be plain text (i.e., = no=20 entity-encoded html).=20
xml:lang= =20 may be used to identify the language of any human readable text.=20
xml:base may be=20 used to control how relative URIs are resolved. =

Sample feed =

<?xml version=3D"1.0" encoding=3D"utf-8"?>
<feed xmlns=3D"http://www.w3.org/2005/Atom">

  <title>Example Feed</title>
  <link href=3D"http://example.org/"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author>
    <name>John Doe</name>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

  <entry>
    <title>Atom-Powered Robots Run Amok</title>
    <link href=3D"http://example.org/2003/12/13/atom03"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <summary>Some text.</summary>
  </entry>

</feed>

Elements of <feed>

A Feed consists of some = metadata,=20 followed by any number of entries.=20

Required feed elements=20

Here's a list of the required feed elements, each with a brief = description,=20 and an example.

<= /TBODY>

Element	Description
id	Identifies the feed using a universally unique and=20 permanent URI. If you=20 have a long-term, renewable lease on your Internet domain name, = then you=20 can feel free to use your website's address. = <id>http://example.com/</id>
title	Contains a human readable title for the feed. Often = the=20 same as the title of the associated website. This value should not = be=20 blank. <title>Example, = Inc.</title>
updated	Indicates the last time the feed was modified in a=20 significant way. = <updated>2003-12-13T18:30:02Z</updated>

Recommended feed elements

Atom makes a number of = additional=20 requirements and recommendations for feed elements that you should to be = aware=20 of. They are as follows:=20

Element	Description
author	Names one author of the feed. A feed may have = multiple=20 `author` elements. A feed must contain at least one=20 `author` element unless all of the = `entry`=20 elements contain at least one `author` element. More = info here.=20 <author> <name>John Doe</name> <email>JohnDoe@example.com</email> <uri>http://example.com/~johndoe</uri> </author>
link	Identifies a related Web page. The type of relation = is=20 defined by the `rel` attribute. A feed is limited to = one=20 `alternate` per `type` and = `hreflang`. A=20 feed should contain a link back to the feed itself. More info here= . <link rel=3D"self" = href=3D"/feed" />

Optional feed elements=20

Here's a list of optional feed elements.

Element	Description
category	Specifies a category that the feed belongs to. A=20 `feed` may have multiple `category` = elements. More=20 info here= .=20 <category term=3D"sports"/>
contributor	Names one contributor to the feed. An feed may have = multiple contributor elements. More info here.=20 <contributor> <name>Jane Doe</name> </contributor>
generator	Identifies the software used to generate the feed, = for=20 debugging and other purposes. Both the uri and = `version`=20 attributes are optional. <generator uri=3D"/myblog.php" = version=3D"1.0"> Example Toolkit </generator>
icon	Identifies a small image which provides iconic = visual=20 identification for the feed. Icons should be square. = <icon>/icon.jpg</icon>
logo	Identifies a larger image which provides visual=20 identification for the feed. Images should be twice as wide as = they are=20 tall. <logo>/logo.jpg</logo>
rights	Conveys information about rights, e.g. copyrights, = held in=20 and over the feed. More info here= . <rights> =A9 2005 John Doe </rights>
subtitle	Contains a human-readable description or subtitle = for the=20 feed. More info here= . <subtitle>all your examples are belong to = us</subtitle>

Elements of <entry>

An example of an entry = would be a=20 single post on a weblog.=20

Required Elements of <entry>

Here's a list of the required feed elements, each with a brief = description,=20 and an example.

<= /TR>

Element	Description
id	Identifies the entry using a universally unique and = permanent URI.=20 Suggestions on how to make a good id can be found here.=20 Two entries in a feed can have the same value for id if they = represent the=20 same entry at different points in time. = <id>http://example.com/blog/1234</id>
title	Contains a human readable title for the entry. This = value=20 should not be blank. <title>Atom-Powered Robots Run = Amok</title>
updated	Indicates the last time the entry was modified in a = significant way. This value need not change after a typo is fixed, = only=20 after a substantial modification. Generally, different entries in = a feed=20 will have different updated timestamps. = <updated>2003-12-13T18:30:02-05:00</updated>

Recommended elements of <entry>

Atom makes a number of = additional=20 requirements and recommendations for entry elements that you should to = be aware=20 of. They are as follows:=20

Element	Description
author	Names one author of the entry. An entry may have = multiple=20 authors. An entry must contain at least one `author` = element=20 unless there is an `author` element in the enclosing=20 `feed`, or there is an `author` element in = the=20 enclosed `source` element. More info here.=20 <author> <name>John Doe</name> </author>
content	Contains or links to the complete content of the = entry.=20 Content must be provided if there is no `alternate` = link, and=20 should be provided if there is no `summary`. More info = here.=20 <content>complete story here</content>
link	Identifies a related Web page. The type of relation = is=20 defined by the `rel` attribute. An entry is limited to = one=20 `alternate` per `type` and = `hreflang`. An=20 entry must contain an `alternate` link if there is no=20 `content` element. More info here= . <link rel=3D"alternate" = href=3D"/blog/1234"/>
summary	Conveys a short summary, abstract, or excerpt of = the entry.=20 Summary should be provided if there either is no content provided = for the=20 entry, or that content is not inline (i.e., contains a src = attribute), or=20 if the content is encoded in base64. More info here= . <summary>Some = text.</summary>

Optional elements of <entry>

Here's a list of optional feed elements.

Element	Description
category	Specifies a category that the entry belongs to. A=20 `entry` may have multiple `category` = elements. More=20 info here= .=20 <category term=3D"technology"/>
contributor	Names one contributor to the entry. An entry may = have=20 multiple `contributor` elements. More info here.=20 <contributor> <name>Jane Doe</name> </contributor>
published	Contains the time of the initial creation or first=20 availability of the entry. = <published>2003-12-13T09:17:51-08:00</published>
source	If an `entry` is copied from one feed = into=20 another feed, then the source `feed`'s metadata (all = child=20 elements of `feed` other than the `entry` = elements)=20 should be preserved if the source `feed` contains any = of the=20 child elements `author,` `contributor,`=20 `rights,` or `category` and those child = elements are=20 not present in the source `entry`. <source> <id>http://example.org/</id> <title>Fourty-Two</title> <updated>2003-12-13T18:30:02Z</updated> <rights>=A9 2005 Example, Inc.</rights> </source>
rights	Conveys information about rights, e.g. copyrights, = held in=20 and over the entry. More info here= . <rights type=3D"html"> &copy; 2005 John Doe </rights>

Common Constructs

Content

<content> either contains, or links to, the = complete=20 content of the entry.

In the most common case, the type attribute is either=20 text, html, xhtml, in which case = the=20 content element is defined identically to other text constructs, which = are=20 described here= .

Otherwise, if the src attribute is present, it = represents the=20 URI of where the = content can=20 be found. The type attribute, if present, is the media type = of the=20 content.

Otherwise, if the type attribute ends in = +xml or=20 /xml, then an xml document of this type is contained = inline.

Otherwise, if the type attribute starts with = text,=20 then an escaped document of this type is contained inline.

Otherwise, a base64=20 encoded document of the indicated media type is contained inline.

Link

<link> is patterned after html's link=20 element. It has one required attribute, href, and five = optional=20 attributes: rel, type, hreflang,=20 title, and length.

href is the URI of the referenced = resource=20 (typically a Web page)

rel contains a single link relationship type. It can be = a full=20 URI (see extensibility),=20 or one of the following predefined values = (default=3Dalternate):

alternate: an alternate representation of the entry = or feed,=20 for example a permalink to the html version of the entry, or the front = page of=20 the weblog.=20
enclosure: a related resource which is potentially = large in=20 size and might require special handling, for example an audio or video = recording.=20
related: an document related to the entry or feed.=20
self: the feed itself.=20
via: the source of the information provided in the = entry.=20

type indicates the media type of the resource.

hreflang indicates the language of the referenced = resource.

title human readable information about the link, = typically for=20 display purposes.

length the length of the resource, in bytes.

Person

<author> and <contributor> = describe a=20 person, corporation, or similar entity. It has one required element,=20 name, and two optional elements: uri,=20 email.

<name> conveys a human-readable name for the = person.

<uri> contains a home page for the person.

<email> contains an email address for the = person.

Text

<title>, <summary>,=20 <content>, and <rights> contain=20 human-readable text, usually in small quantities. The type=20 attribute determines how this information is encoded = (default=3D"text")

If type=3D"text", then this element contains plain text = with no=20 entity escaped html.

<title type=3D"text">AT&amp;T =
bought by SBC!</title>

If type=3D"html", then this element contains entity = escaped=20 html.

<title type=3D"html">
  AT&amp;amp;T bought &lt;b&gt;by =
SBC&lt;/b&gt;!
</title>

If type=3D"xhtml", then this element contains inline = xhtml,=20 wrapped in a div element.

<title type=3D"xhtml">
  <div xmlns=3D"http://www.w3.org/1999/xhtml">
    AT&amp;T bought <b>by SBC</b>!
  </div>
</title>

Extending Atom

The atom content element is designed to support the direct inclusion = of other=20 XML vocabularies.

Any fully qualified URI=20 may be used a value for the rel attribute of link = elements.

Elements from other namespaces may be included pretty much anywhere. = This=20 means that most RSS=20 1.0 and RSS=20 2.0 modules may be used in Atom.