OPML conventions (draft)

Suggestions for producing OPML that is compliant and easy to parse

References: Full OPML 1.0 specification

16/10/2005 - Dave Winer has put up Guidelines for validating OPML

The OPML spec is very flexible, allowing the creation of arbitrary element attributes as the application requires. This has led to the criticism that it is difficult to parse consistently. The issue is that a representation of a feature can differ depending on the developer’s interpretation or implementation.

For example, a widespread use of OPML is for the transport of RSS subscriptions. Here are some ways a subscription is represented in valid OPML:

<outline xmlUrl="http://www.example.com/rss.xml" />
<outline type="rss" xmlUrl="http://www.example.com/rss.xml" />
<outline type="rss" url="http://www.example.com/rss.xml" />

The goal of this document is not to replace the OPML spec or impose limitations on the use of OPML. Most of these issues have been hashed out already. Instead, this page collects usage recommendations that will make your OPML easy to read and use by 3rd party developers. These aim at consistency and standardizing the already commonly used tags

The most popular application of OPML is to represent a group of RSS feeds, as described above. The recommendation is to represent these feed types as:

<outline type="rss" url="http://www.example.com/rss.xml" />

This representation utilizes the url attribute, which is commonly used to describe the primary URL of the outline. It strengthens the usage of the “url” attribute (which is not part of the 1.0 standard) without specializing it with a prefix.

If supplementary URLs are required (e.g. htmlUrl to link to the site web page) they can be added as usual. These less-used attributes will then only be recognized by specific applications.

Here are the commonly used type attribute values:

As OPML is an XML spec it should be readable by XML compliant parsers. This has implications for the representation of text within nodes.

Attributes should not contain the unescaped ampersand character ‘&’ or nested double quotes ‘“‘. This is usually seen in links to CGI genereated pages. For example:

<outline url="http://www.example.com/page?view=index&user=me" />

The ‘&’ in ‘view=index&user=me’ will cause many XML parsers to choke. The recommendation here is to escape these characters, in a similar manner to XHTML. The above example then becomes:

<outline url="http://www.example.com/page?view=index&amp;user=me" />

Similarly the following element will not validate:

<outline url="http://www.example.com/page?view="index"&amp;user=me" />

The use of the double-quote will confuse many XML parsers during attribute parsing. An XML compliant implementation would look like this:

<outline url="http://www.example.com/page?view=&dquot;index&dquot;&amp;user=me" />

This is a particularly important recommendation because most people do not write their own XML parsers and are constrained to whatever tools are available on their development platform. It is not too hard to make your application output well-formed XML, but it is difficult and arguably harmful to work around malformed XML.

In some files, a title attribute is used to represent the textual content instead of text. This is done to indicate some kind of formatting attribute on the text, or structural significance. For example:

<outline title="The Trouble with Tribbles">
  <outline text="It all began last night..." />
</outline>

The recommendation here is to always use the text attribute to hold textual content, and create attributes to indicate application specific formatting. The above example could be represent as follows:

<outline text="The Trouble with Tribbles" format="title">
  <outline text="It all began last night..." />
</outline>

1st draft: 13 October 2005, Dan V

The OPML validator doesn’t like your suggested syntax up there; it says that the xmlUrl attribute is required if type=”rss”, and in that case the url attribute isn’t allowed. – PhillipPearson