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
}
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.
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 "<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.
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.
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 "&" and "<" 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.
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
"&" and "<" 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.
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:
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
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].
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 "&" and "<" 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 }
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*)
}
The atom:source element is designed to allow the aggregation of
entries from different feeds while retaining information about an
entry’s source feed. For this reason, Atom Processors that are
performing such aggregation SHOULD include at least the required
feed-level Metadata elements (atom:id, atom:title, and atom:updated)
in the atom:source element.
4.2.12. The "atom:subtitle" Element
The "atom:subtitle" element is a Text construct that conveys a human-
readable description or subtitle for a feed.
atomSubtitle = element atom:subtitle { atomTextConstruct }
4.2.13. The "atom:summary" Element
The "atom:summary" element is a Text construct that conveys a short
summary, abstract, or excerpt of an entry.
atomSummary = element atom:summary { atomTextConstruct }
It is not advisable for the atom:summary element to duplicate
atom:title or atom:content because Atom Processors might assume there
is a useful summary when there is none.
4.2.14. The "atom:title" Element
The "atom:title" element is a Text construct that conveys a human-
readable title for an entry or feed.
atomTitle = element atom:title { atomTextConstruct }
4.2.15. The "atom:updated" Element
The "atom:updated" element is a Date construct indicating the most
recent instant in time when an entry or feed was modified in a way
the publisher considers significant. Therefore, not all
modifications necessarily result in a changed atom:updated value.
atomUpdated = element atom:updated { atomDateConstruct }
Publishers MAY change the value of this element over time.
5. Securing Atom Documents
Because Atom is an XML-based format, existing XML security mechanisms
can be used to secure its content.
Producers of feeds and/or entries, and intermediaries who aggregate
feeds and/or entries, may have sound reasons for signing and/or
encrypting otherwise-unprotected content. For example, a merchant
might digitally sign a message that contains a discount coupon for
its products. A bank that uses Atom to deliver customer statements
is very likely to want to sign and encrypt those messages to protect
their customers’ financial information and to assure the customer of
their authenticity. Intermediaries may want to encrypt aggregated
feeds so that a passive observer cannot tell what topics the
recipient is interested in. Of course, many other examples exist as
well.
The algorithm requirements in this section pertain to the Atom
Processor. They require that a recipient, at a minimum, be able to
handle messages that use the specified cryptographic algorithms.
These requirements do not limit the algorithms that the sender can
choose.
5.1. Digital Signatures
The root of an Atom Document (i.e., atom:feed in an Atom Feed
Document, atom:entry in an Atom Entry Document) or any atom:entry
element MAY have an Enveloped Signature, as described by XML-
Signature and Syntax Processing [W3C.REC-xmldsig-core-20020212].
Atom Processors MUST NOT reject an Atom Document containing such a
signature because they are not capable of verifying it; they MUST
continue processing and MAY inform the user of their failure to
validate the signature.
In other words, the presence of an element with the namespace URI
"http://www.w3.org/2000/09/xmldsig#" and a local name of "Signature"
as a child of the document element MUST NOT cause an Atom Processor
to fail merely because of its presence.
Other elements in an Atom Document MUST NOT be signed unless their
definitions explicitly specify such a capability.
Section 6.5.1 of [W3C.REC-xmldsig-core-20020212] requires support for
Canonical XML [W3C.REC-xml-c14n-20010315]. However, many
implementers do not use it because signed XML documents enclosed in
other XML documents have their signatures broken. Thus, Atom
Processors that verify signed Atom Documents MUST be able to
canonicalize with the exclusive XML canonicalization method
identified by the URI "http://www.w3.org/2001/10/xml-exc-c14n#", as
specified in Exclusive XML Canonicalization
[W3C.REC-xml-exc-c14n-20020718].
Intermediaries such as aggregators may need to add an atom:source
element to an entry that does not contain its own atom:source