Home >> FAQs/Tutorials >> RSS Tutorials >> Index

RSS Tutorials - The Atom Syndication Format - Part 2

By: M. Nottingham, Ed. & R. Sayre, Ed.

(Continued from previous topic...)

The Atom Syndication Format - Part 2


   atom:content element when that element is present, and a non-empty
   atom:summary element when the entry contains no atom:content element.
   However, the absence of atom:summary is not an error, and Atom
   Processors MUST NOT fail to function correctly as a consequence of
   such an absence.

4.1.2.  The "atom:entry" Element

   The "atom:entry" element represents an individual entry, acting as a
   container for metadata and data associated with the entry.  This
   element can appear as a child of the atom:feed element, or it can
   appear as the document (i.e., top-level) element of a stand-alone
   Atom Entry Document.

   atomEntry =
      element atom:entry {
         atomCommonAttributes,
         (atomAuthor*
          & atomCategory*
          & atomContent?
          & atomContributor*
          & atomId
          & atomLink*
          & atomPublished?
          & atomRights?
          & atomSource?
          & atomSummary?
          & atomTitle
          & atomUpdated
          & extensionElement*)
      }

   This specification assigns no significance to the order of appearance
   of the child elements of atom:entry.

   The following child elements are defined by this specification (note
   that it requires the presence of some of these elements):

   o  atom:entry elements MUST contain one or more atom:author elements,
      unless the atom:entry contains an atom:source element that
      contains an atom:author element or, in an Atom Feed Document, the
      atom:feed element contains an atom:author element itself.
   o  atom:entry elements MAY contain any number of atom:category
      elements.
   o  atom:entry elements MUST NOT contain more than one atom:content
      element.
   o  atom:entry elements MAY contain any number of atom:contributor
      elements.

[Page 13]

   o  atom:entry elements MUST contain exactly one atom:id element.
   o  atom:entry elements that contain no child atom:content element
      MUST contain at least one atom:link element with a rel attribute
      value of "alternate".
   o  atom:entry elements MUST NOT contain more than one atom:link
      element with a rel attribute value of "alternate" that has the
      same combination of type and hreflang attribute values.
   o  atom:entry elements MAY contain additional atom:link elements
      beyond those described above.
   o  atom:entry elements MUST NOT contain more than one atom:published
      element.
   o  atom:entry elements MUST NOT contain more than one atom:rights
      element.
   o  atom:entry elements MUST NOT contain more than one atom:source
      element.
   o  atom:entry elements MUST contain an atom:summary element in either
      of the following cases:
      *  the atom:entry contains an atom:content that has a "src"
         attribute (and is thus empty).
      *  the atom:entry contains content that is encoded in Base64;
         i.e., the "type" attribute of atom:content is a MIME media type
         [MIMEREG], but is not an XML media type [RFC3023], does not
         begin with "text/", and does not end with "/xml" or "+xml".
   o  atom:entry elements MUST NOT contain more than one atom:summary
      element.
   o  atom:entry elements MUST contain exactly one atom:title element.
   o  atom:entry elements MUST contain exactly one atom:updated element.

4.1.3.  The "atom:content" Element

   The "atom:content" element either contains or links to the content of
   the entry.  The content of atom:content is Language-Sensitive.

   atomInlineTextContent =
      element atom:content {
         atomCommonAttributes,
         attribute type { "text" | "html" }?,
         (text)*
      }

   atomInlineXHTMLContent =
      element atom:content {
         atomCommonAttributes,
         attribute type { "xhtml" },
         xhtmlDiv
      }

[Page 14]

   atomInlineOtherContent =
      element atom:content {
         atomCommonAttributes,
         attribute type { atomMediaType }?,
         (text|anyElement)*
      }

   atomOutOfLineContent =
      element atom:content {
         atomCommonAttributes,
         attribute type { atomMediaType }?,
         attribute src { atomUri },
         empty
      }

   atomContent = atomInlineTextContent
    | atomInlineXHTMLContent
    | atomInlineOtherContent
    | atomOutOfLineContent

4.1.3.1.  The "type" Attribute

   On the atom:content element, the value of the "type" attribute MAY be
   one of "text", "html", or "xhtml".  Failing that, it MUST conform to
   the syntax of a MIME media type, but MUST NOT be a composite type
   (see Section 4.2.6 of [MIMEREG]).  If neither the type attribute nor
   the src attribute is provided, Atom Processors MUST behave as though
   the type attribute were present with a value of "text".

4.1.3.2.  The "src" Attribute

   atom:content MAY have a "src" attribute, whose value MUST be an IRI
   reference [RFC3987].  If the "src" attribute is present, atom:content
   MUST be empty.  Atom Processors MAY use the IRI to retrieve the
   content and MAY choose to ignore remote content or to present it in a
   different manner than local content.

   If the "src" attribute is present, the "type" attribute SHOULD be
   provided and MUST be a MIME media type [MIMEREG], rather than "text",
   "html", or "xhtml".  The value is advisory; that is to say, when the
   corresponding URI (mapped from an IRI, if necessary) is dereferenced,
   if the server providing that content also provides a media type, the
   server-provided media type is authoritative.

[Page 15]

4.1.3.3.  Processing Model

   Atom Documents MUST conform to the following rules.  Atom Processors
   MUST interpret atom:content according to the first applicable rule.

   1.  If the value of "type" is "text", the content of atom:content
       MUST NOT contain child elements.  Such text is intended to be
       presented to humans in a readable fashion.  Thus, Atom Processors
       MAY collapse white space (including line breaks), and display the
       text using typographic techniques such as justification and
       proportional fonts.

   2.  If the value of "type" is "html", the content of atom:content
       MUST NOT contain child elements and SHOULD be suitable for
       handling as HTML [HTML].  The HTML markup MUST be escaped; for
       example, "<br>" as "&lt;br>".  The HTML markup SHOULD be such
       that it could validly appear directly within an HTML <DIV>
       element.  Atom Processors that display the content MAY use the
       markup to aid in displaying it.

   3.  If the value of "type" is "xhtml", the content of atom:content
       MUST be a single XHTML div element [XHTML] and SHOULD be suitable
       for handling as XHTML.  The XHTML div element itself MUST NOT be
       considered part of the content.  Atom Processors that display the
       content MAY use the markup to aid in displaying it.  The escaped
       versions of characters such as "&" and ">" represent those
       characters, not markup.

   4.  If the value of "type" is an XML media type [RFC3023] or ends
       with "+xml" or "/xml" (case insensitive), the content of
       atom:content MAY include child elements and SHOULD be suitable
       for handling as the indicated media type.  If the "src" attribute
       is not provided, this would normally mean that the "atom:content"
       element would contain a single child element that would serve as
       the root element of the XML document of the indicated type.

   5.  If the value of "type" begins with "text/" (case insensitive),
       the content of atom:content MUST NOT contain child elements.

   6.  For all other values of "type", the content of atom:content MUST
       be a valid Base64 encoding, as described in [RFC3548], section 3.
       When decoded, it SHOULD be suitable for handling as the indicated
       media type.  In this case, the characters in the Base64 encoding
       MAY be preceded and followed in the atom:content element by white
       space, and lines are separated by a single newline (U+000A)
       character.

[Page 16]

4.1.3.4.  Examples

   XHTML inline:

   ...
   <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
         This is <b>XHTML</b> content.
      </div>
   </content>
   ...
   <content type="xhtml">
      <xhtml:div xmlns:xhtml="http://www.w3.org/1999/xhtml">
         This is <xhtml:b>XHTML</xhtml:b> content.
      </xhtml:div>
   </content>
   ...

   The following example assumes that the XHTML namespace has been bound
   to the "xh" prefix earlier in the document:

   ...
   <content type="xhtml">
      <xh:div>
         This is <xh:b>XHTML</xh:b> content.
      </xh:div>
   </content>
   ...

4.2.  Metadata Elements

4.2.1.  The "atom:author" Element

   The "atom:author" element is a Person construct that indicates the
   author of the entry or feed.

   atomAuthor = element atom:author { atomPersonConstruct }

   If an atom:entry element does not contain atom:author elements, then
   the atom:author elements of the contained atom:source element are
   considered to apply.  In an Atom Feed Document, the atom:author
   elements of the containing atom:feed element are considered to apply
   to the entry if there are no atom:author elements in the locations
   described above.

[Page 17]

4.2.2.  The "atom:category" Element

   The "atom:category" element conveys information about a category
   associated with an entry or feed.  This specification assigns no
   meaning to the content (if any) of this element.

   atomCategory =
      element atom:category {
         atomCommonAttributes,
         attribute term { text },
         attribute scheme { atomUri }?,
         attribute label { text }?,
         undefinedContent
      }

4.2.2.1.  The "term" Attribute

   The "term" attribute is a string that identifies the category to
   which the entry or feed belongs.  Category elements MUST have a
   "term" attribute.

4.2.2.2.  The "scheme" Attribute

   The "scheme" attribute is an IRI that identifies a categorization
   scheme.  Category elements MAY have a "scheme" attribute.

4.2.2.3.  The "label" Attribute

   The "label" attribute provides a human-readable label for display in
   end-user applications.  The content of the "label" attribute is
   Language-Sensitive.  Entities such as "&amp;" and "&lt;" represent
   their corresponding characters ("&" and "<", respectively), not
   markup.  Category elements MAY have a "label" attribute.

4.2.3.  The "atom:contributor" Element

   The "atom:contributor" element is a Person construct that indicates a
   person or other entity who contributed to the entry or feed.

   atomContributor = element atom:contributor { atomPersonConstruct }

4.2.4.  The "atom:generator" Element

   The "atom:generator" element's content identifies the agent used to
   generate a feed, for debugging and other purposes.

[Page 18]

   atomGenerator = element atom:generator {
      atomCommonAttributes,
      attribute uri { atomUri }?,
      attribute version { text }?,
      text
   }

   The content of this element, when present, MUST be a string that is a
   human-readable name for the generating agent.  Entities such as
   "&amp;" and "&lt;" represent their corresponding characters ("&" and
   "<" respectively), not markup.

   The atom:generator element MAY have a "uri" attribute whose value
   MUST be an IRI reference [RFC3987].  When dereferenced, the resulting
   URI (mapped from an IRI, if necessary) SHOULD produce a
   representation that is relevant to that agent.

   The atom:generator element MAY have a "version" attribute that
   indicates the version of the generating agent.

4.2.5.  The "atom:icon" Element

   The "atom:icon" element's content is an IRI reference [RFC3987] that
   identifies an image that provides iconic visual identification for a
   feed.

   atomIcon = element atom:icon {
      atomCommonAttributes,
      (atomUri)
   }

   The image SHOULD have an aspect ratio of one (horizontal) to one
   (vertical) and SHOULD be suitable for presentation at a small size.

4.2.6.  The "atom:id" Element

   The "atom:id" element conveys a permanent, universally unique
   identifier for an entry or feed.

   atomId = element atom:id {
      atomCommonAttributes,
      (atomUri)
   }

   Its content MUST be an IRI, as defined by [RFC3987].  Note that the
   definition of "IRI" excludes relative references.  Though the IRI
   might use a dereferencable scheme, Atom Processors MUST NOT assume it
   can be dereferenced.

[Page 19]

   When an Atom Document is relocated, migrated, syndicated,
   republished, exported, or imported, the content of its atom:id
   element MUST NOT change.  Put another way, an atom:id element
   pertains to all instantiations of a particular Atom entry or feed;
   revisions retain the same content in their atom:id elements.  It is
   suggested that the atom:id element be stored along with the
   associated resource.

   The content of an atom:id element MUST be created in a way that
   assures uniqueness.

   Because of the risk of confusion between IRIs that would be
   equivalent if they were mapped to URIs and dereferenced, the
   following normalization strategy SHOULD be applied when generating
   atom:id elements:

   o  Provide the scheme in lowercase characters.
   o  Provide the host, if any, in lowercase characters.
   o  Only perform percent-encoding where it is essential.
   o  Use uppercase A through F characters when percent-encoding.
   o  Prevent dot-segments from appearing in paths.
   o  For schemes that define a default authority, use an empty
      authority if the default is desired.
   o  For schemes that define an empty path to be equivalent to a path
      of "/", use "/".
   o  For schemes that define a port, use an empty port if the default
      is desired.
   o  Preserve empty fragment identifiers and queries.
   o  Ensure that all components of the IRI are appropriately character
      normalized, e.g., by using NFC or NFKC.

4.2.6.1.  Comparing atom:id

   Instances of atom:id elements can be compared to determine whether an
   entry or feed is the same as one seen before.  Processors MUST
   compare atom:id elements on a character-by-character basis (in a
   case-sensitive fashion).  Comparison operations MUST be based solely
   on the IRI character strings and MUST NOT rely on dereferencing the
   IRIs or URIs mapped from them.

   As a result, two IRIs that resolve to the same resource but are not
   character-for-character identical will be considered different for
   the purposes of identifier comparison.

   For example, these are four distinct identifiers, despite the fact
   that they differ only in case:

[Page 20]

      http://www.example.org/thing
      http://www.example.org/Thing
      http://www.EXAMPLE.org/thing
      HTTP://www.example.org/thing

   Likewise, these are three distinct identifiers, because IRI
   %-escaping is significant for the purposes of comparison:

      http://www.example.com/~bob
      http://www.example.com/%7ebob
      http://www.example.com/%7Ebob

4.2.7.  The "atom:link" Element

   The "atom:link" element defines a reference from an entry or feed to
   a Web resource.  This specification assigns no meaning to the content
   (if any) of this element.

   atomLink =
      element atom:link {
         atomCommonAttributes,
         attribute href { atomUri },
         attribute rel { atomNCName | atomUri }?,
         attribute type { atomMediaType }?,
         attribute hreflang { atomLanguageTag }?,
         attribute title { text }?,
         attribute length { text }?,
         undefinedContent
      }

4.2.7.1.  The "href" Attribute

   The "href" attribute contains the link's IRI. atom:link elements MUST
   have an href attribute, whose value MUST be a IRI reference
   [RFC3987].

4.2.7.2.  The "rel" Attribute

   atom:link elements MAY have a "rel" attribute that indicates the link
   relation type.  If the "rel" attribute is not present, the link
   element MUST be interpreted as if the link relation type is
   "alternate".

   The value of "rel" MUST be a string that is non-empty and matches
   either the "isegment-nz-nc" or the "IRI" production in [RFC3987].
   Note that use of a relative reference other than a simple name is not
   allowed.  If a name is given, implementations MUST consider the link
   relation type equivalent to the same name registered within the IANA

[Page 21]

   Registry of Link Relations (Section 7), and thus to the IRI that
   would be obtained by appending the value of the rel attribute to the
   string "http://www.iana.org/assignments/relation/".  The value of
   "rel" describes the meaning of the link, but does not impose any
   behavioral requirements on Atom Processors.

   This document defines five initial values for the Registry of Link
   Relations:

   1.  The value "alternate" signifies that the IRI in the value of the
       href attribute identifies an alternate version of the resource
       described by the containing element.

   2.  The value "related" signifies that the IRI in the value of the
       href attribute identifies a resource related to the resource
       described by the containing element.  For example, the feed for a
       site that discusses the performance of the search engine at
       "http://search.example.com" might contain, as a child of
       atom:feed:

       <link rel="related" href="http://search.example.com/"/>

       An identical link might appear as a child of any atom:entry whose
       content contains a discussion of that same search engine.

   3.  The value "self" signifies that the IRI in the value of the href
       attribute identifies a resource equivalent to the containing
       element.

   4.  The value "enclosure" signifies that the IRI in the value of the
       href attribute identifies a related resource that is potentially
       large in size and might require special handling.  For atom:link
       elements with rel="enclosure", the length attribute SHOULD be
       provided.

   5.  The value "via" signifies that the IRI in the value of the href
       attribute identifies a resource that is the source of the
       information provided in the containing element.

4.2.7.3.  The "type" Attribute

   On the link element, the "type" attribute's value is an advisory
   media type: it is a hint about the type of the representation that is
   expected to be returned when the value of the href attribute is
   dereferenced.  Note that the type attribute does not override the
   actual media type returned with the representation.  Link elements
   MAY have a type attribute, whose value MUST conform to the syntax of
   a MIME media type [MIMEREG].

[Page 22]

4.2.7.4.  The "hreflang" Attribute

   The "hreflang" attribute's content describes the language of the
   resource pointed to by the href attribute.  When used together with
   the rel="alternate", it implies a translated version of the entry.
   Link elements MAY have an hreflang attribute, whose value MUST be a
   language tag [RFC3066].

4.2.7.5.  The "title" Attribute

   The "title" attribute conveys human-readable information about the
   link.  The content of the "title" attribute is Language-Sensitive.
   Entities such as "&amp;" and "&lt;" represent their corresponding
   characters ("&" and "<", respectively), not markup.  Link elements
   MAY have a title attribute.

4.2.7.6.  The "length" Attribute

   The "length" attribute indicates an advisory length of the linked
   content in octets; it is a hint about the content length of the
   representation returned when the IRI in the href attribute is mapped
   to a URI and dereferenced.  Note that the length attribute does not
   override the actual content length of the representation as reported
   by the underlying protocol.  Link elements MAY have a length
   attribute.

4.2.8.  The "atom:logo" Element

   The "atom:logo" element's content is an IRI reference [RFC3987] that
   identifies an image that provides visual identification for a feed.

   atomLogo = element atom:logo {
      atomCommonAttributes,
      (atomUri)
   }

   The image SHOULD have an aspect ratio of 2 (horizontal) to 1
   (vertical).

4.2.9.  The "atom:published" Element

   The "atom:published" element is a Date construct indicating an
   instant in time associated with an event early in the life cycle of
   the entry.

   atomPublished = element atom:published { atomDateConstruct }

[Page 23]

   Typically, atom:published will be associated with the initial
   creation or first availability of the resource.

4.2.10.  The "atom:rights" Element

   The "atom:rights" element is a Text construct that conveys
   information about rights held in and over an entry or feed.

   atomRights = element atom:rights { atomTextConstruct }

   The atom:rights element SHOULD NOT be used to convey machine-readable
   licensing information.

   If an atom:entry element does not contain an atom:rights element,
   then the atom:rights element of the containing atom:feed element, if
   present, is considered to apply to the entry.

4.2.11.  The "atom:source" Element

   If an atom:entry is copied from one feed into another feed, then the
   source atom:feed's metadata (all child elements of atom:feed other
   than the atom:entry elements) MAY be preserved within the copied
   entry by adding an atom:source child element, if it is not already
   present in the entry, and including some or all of the source feed's
   Metadata elements as the atom:source element's children.  Such
   metadata SHOULD be preserved if the source atom:feed contains any of
   the child elements atom:author, atom:contributor, atom:rights, or
   atom:category and those child elements are not present in the source
   atom:entry.

   atomSource =
      element atom:source {
         atomCommonAttributes,
         (atomAuthor*
          & atomCategory*
          & atomContributor*
          & atomGenerator?
          & atomIcon?
          & atomId?
          & atomLink*
          & atomLogo?
          & atomRights?
          & atomSubtitle?
          & atomTitle?
          & atomUpdated?
          & extensionElement*)
      }

[Page 24]

(Continued on next topic...)

  1. The Atom Syndication Format - Reference Document
  2. The Atom Syndication Format - Part 2
  3. The Atom Syndication Format - Part 3
  4. The Atom Syndication Format - Part 4

Selected Developer Jobs:

More...