UserPreferences

SyntaxGuidelines


Syntax Guidelines

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.

Naming

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.

Element Example:

<create-entry />

Attribute Example:

<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:

Common element usage

The following actual elements should only be used in the ways specified below.

Namespace

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.

Presentable content

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>

Non-presentable content

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.