| About
Home
Spec
Directory
Validator
Editor
|
|
|
|
Guidelines for validating OPML
Posted by dave@scripting.com, 10/14/05 at 11:26:55 AM.
Status 
| | 10/14/05: Request for comments.
|
Goal
| | I want to make it easy for people to write OPML validators. I am writing 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.
|
Other special attributes
| | In addition to the text attribute, several others, by convention, can appear on any outline node. Two are specifically mentioned in the 1.0 spec: isBreakpoint and isComment. There are others in common use and should be checked by validators.
|
| | created is the date that the outline node was created. I have used this attribute in my weblog editors as a key to generate a permalink for the item.
|
| | category is a string of comma-separated slash-delimited category strings, in the format defined by the RSS 2.0 category element. I use this attribute in Scripting News OPML, and in the outlines generated by the OPML Editor to indicate the categories the items were routed to. A test case with the category attribute.
|
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, it should not be omitted.
|
| | 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.
|
Change notes
| | outline elements outside the body element
|
| | Nick Bradbury suggested that the validator should check for outline elements outside the body element, I let the idea settle in a week, and agree. The validator now checks this case. I added a test case that has an outline element in the head section.
|
| | Subscription list title & text
|
| | The first version of the guidelines suggested omitting the title attribute when it's the same as the text attribute in subscription lists, but after a discussion with Nick Bradbury, I became convinced that this was bad advice.
|
| | The two attributes serve different purposes. Some processors will look for title, and not care about text (they're not outline editors) and others will look for text and just pass-through title (and the other subscription list attributes).
|
| | So it makes sense to include both. Note that title is optional, but text is not.
|
| | Added a new section explaining special attributes such as isBreakpoint, isComment, created and category.
|
|
