| About
Home
Spec
Directory
Editor
|
|
|
|
Guidelines for validating OPML
Fri, Oct 14, 2005; by Dave Winer.
Status 
| | 10/14/05: Request for comments.
|
Goal
| | I want to make it easy for people to write OPML validators. I plan to write one myself. In order to do that, we need to sort out the different attributes that are appearing in OPML documents, and decide which should be supported by all processors, which should be flagged as errors by a validator, and which we should warn developers about.
|
| | Nothing in this document is meant to override what's stated in the spec for OPML, or the spec for XML; if there's disagreement those two documents take precedence.
|
| | As with all other work, common sense rules above all else, and all the usual disclaimers apply. 
|
Prior art
| | Dan V (not sure of his last name) has a crib sheet of common practice in OPML.
|
| | If you know of other work in this area, please send me a pointer.
|
Text attribute
| | Every outline element must have at least a text attribute, which is what is displayed when an outliner opens the OPML file. To omit the text attribute would render the outline useless in an outliner. This is what the user would see -- clearly an unacceptable user experience.
|
| | Part of the purpose of producing OPML is to give users the power to accumulate and organize related information in an outliner. This may be an even more important use for OPML than data interchange.
|
| | I take responsibility for this not being well enough understood in the community, until writing this document you had to actually use an outliner to see why the text attribute is so essential.
|
| | A missing text attribute in any outline element is an error.
|
Subscription lists
| | A subscription list document is a possibly multiple-level list of subscriptions to feeds. Each sub-element of the body of the OPML document is a node of type rss or an outline element that contains nodes of type rss.
|
| | Today, most subscription lists are a flat sequence of rss nodes, but some aggregators allow categorized subscription lists that are arbitrarily structured. A validator may flag these files, warning that some processors may not understand and preserve the structure.
|
| | Required attributes: type, text, xmlUrl.
|
| | For outline elements whose type is rss, the text attribute is almost always the top-level title element in the feed being pointed to.
|
| | xmlUrl is the http address of the feed.
|
| | Optional attributes: description, htmlUrl, language, title, version.
|
| | These attributes are useful when presenting a list of subscriptions to a user, except for version, they are all derived from information in the feed itself.
|
| | description is the top-level description element from the feed. htmlUrl is the top-level link element. language is the value of the top-level language element. title is probably the same as text, and if so should be omitted (validators may flag this with an advisory).
|
| | version varies depending on the version of RSS that's being supplied. It was invented at a time when we thought there might be some processors that only handled certain versions, but that hasn't turned out to be a major issue. The values it can have are: RSS1 for RSS 1.0; RSS for 0.91, 0.92 or 2.0; scriptingNews for scriptingNews format. There are no known values for Atom feeds, but they certainly could be provided.
|
Directories
| | A directory may contain an arbitrary structure of outline elements with type link or rss, and possibly other types.
|
| | For outline elements whose type is link, the text element is, as usual, what's displayed in the outliner, and it's also what is displayed in the HTML rendering in the directory.
|
| | When a link element is expanded in an outliner, if the address ends with ".opml", the outline expands in place. This is called inclusion. A validator should check that the OPML file being pointed to is accessible, and may wish to validate the pointed-to file as well.
|
| | If the address does not end with ".opml" the link is assumed to point to something that can be displayed in a web browser.
|
Other elements, attributes
| | It should go without saying that validators must check the values of the sub-elements of the head element, and the isBreakpoint and isComment attributes, as discussed in the spec.
|
|
