This page tries to define some simple syntax guidelines, which should apply to the Atom format -- both existing and future extensions of it. Except where explicitly stated otherwise, all examples provided are fictional: the elements and attributes given, may or may not exist in the Atom Format syntax.
Names should be all lower-case, and if possible, one word only. If names need to be two or more words, they should be separated with a hyphen.
<link service-type="..." />
Enumerated Attribute or Element Values Example:
<link rel="in-reply-to" .../>
Common attribute names
The following attribute names should be used only in the ways specified below. For attributes with other purposes, please choose another name:
href: specifies the URI of something that will usually be conceptually external to the entry, such as a PDF report on a website to which the entry refers.
src: specifies the URI of some external entity intended to be "imported into" the entry--something that is conceptually an integral part of the entry. For example, <content src="..." />.
type: specifies a MIME type, such as "text/html" or "image/jpeg".
Common element usage
The following actual elements should only be used in the ways specified below.
link: Purposes of link elements are specified by a list of legal values for link/@rel, and we are considering allowing extensions to specify additional values. If the external resource being referred to is not one that would make sense to present to the user as a clickable link, some other element should be used instead. For example, link is used to point to an alternate representation of the content of the entry, to the next set of entries in a feed, etc. The link element is not appropriate for pointing to things like a stylesheet for the feed, an XSL template, etc., which are not intended for viewing by the user.
All elements that will be in the Atom specification should use the Atom namespace 'http://purl.org/atom/ns#'. Attributes in Atom feeds should not have any declared namespace.
How to embed content
This section tries to explain how different data types of XML documents should be embedded in Atom documents.
This is content that will be visually, audibly or in some other way, presented to the user. It is not hidden behind the scenes, and it is not insignificant for various presentations of an Atom entry. It is valuable information the visual or audible representation needs or somehow can utilize in the user interface.
This content should be embedded in Atom as element values:
<title>I am a visually or audibly presentable piece of text!</title>
This is content that will be completely hidden from the user. The user should never have to need or care what the hidden content is, unless he or she is doing debugging or some other developmental activities with the document.
This content should be embedded in Atom as attribute values:
<link rel="alternate" />
«Nice to know» content
This is content that may or may not be presented to the user. Whether it should be presented or not, is defined by the situation.
This content can be in either elements or attributes.
- Depending on the use-case. If a value will be presented to the user in more than 50% of the use-cases, it should be embedded as an element value. If it is presented to the user in less than 50% of the use-cases, it should be embedded as an attribute value. The method of embedding must be either as an element or attribute value; it cannot be both.
[AnneVanKesteren] Isn't this in conflict with the SRC attribute for the CONTENT element? I thought that was a case where the majority was against embedding the binary content?
[AsbjornUlsberg] Consensus seems to be that embedding binary content is no-no. I don't see why that has anything to do with the above, though, but it may need some rephrasing. Please feel free to edit it to reflect this better. I have no idea what it should say at the moment.