OPML 1.0

Note

The OPML 1.0 specification is available at:

http://2005.opml.org/spec1.html

It is copied here for posterity under the terms at the bottom of this page.

About this document

This document describes a format for storing outlines in XML 1.0 called Outline Processor Markup Language or OPML.

For the purposes of this document, an outline is a tree, where each node contains a set of named attributes with string values.

Timeline

Outlines have been a popular way to organize information on computers for a long time. While the history of outlining software is unclear, a rough timeline is possible.

Probably the first outliner was developed by Doug Engelbart, as part of the Augment system in the 1960s.

Living Videotext, 1981-87, developed several popular outliners for personal computers. They are archived on a UserLand website, outliners.com.

Frontier, first shipped in 1992, is built around outlining. The text, menu and script editors in Frontier are outliners, as is the object database browser.

XML 1.0, the format that OPML is based on, is a recommendation of the W3C.

Radio UserLand, first shipped in March 2001, is an outliner whose native file format is OPML.

OPML is used for directories in Manila.

Examples

Outlines can be used for specifications, legal briefs, product plans, presentations, screenplays, directories, diaries, discussion groups, chat systems and stories.

Outliners are programs that allow you to read, edit and reorganize outlines.

A screenshot of an outliner application with a hierarchical "To do" list.

Examples of OPML documents: play list, specification, presentation.

Goals of the OPML format

The purpose of this format is to provide a way to exchange information between outliners and Internet services that can be browsed or controlled through an outliner.

The design goal is to have a transparently simple, self-documenting, extensible and human readable format that’s capable of representing a wide variety of data that’s easily browsed and edited. As the format evolves this goal will be preserved. It should be possible for a reasonably technical person to fully understand the format with a quick read of a single Web page.

It’s an open format, meaning that other outliner vendors and service developers are free to use the format to be compatible with Radio UserLand or for any other purpose.

What is an <opml>?

<opml> is an XML element, with a single required attribute, version; a <head> element and a <body> element, both of which are required.

The version attribute is a version string, of the form, x.y, where x and y are both numeric strings.

What is a <head>?

A <head> contains zero or more optional elements, described below.

<title> is the title of the document.

<dateCreated> is a date-time, indicating when the document was created.

<dateModified> is a date-time, indicating when the document was last modified.

<ownerName> is a string, the owner of the document.

<ownerEmail> is a string, the email address of the owner of the document.

<expansionState> is a comma-separated list of line numbers that are expanded. The line numbers in the list tell you which headlines to expand. The order is important. For each element in the list, X, starting at the first summit, navigate flatdown X times and expand. Repeat for each element in the list.

<vertScrollState> is a number, saying which line of the outline is displayed on the top line of the window. This number is calculated with the expansion state already applied.

<windowTop> is a number, the pixel location of the top edge of the window.

<windowLeft> is a number, the pixel location of the left edge of the window.

<windowBottom> is a number, the pixel location of the bottom edge of the window.

<windowRight> is a number, the pixel location of the right edge of the window.

<head> notes

All the sub-elements of <head> may be ignored by the processor. If an outline is opened within another outline, the processor must ignore the windowXxx elements, those elements only control the size and position of outlines that are opened in their own windows.

All date-times conform to the Date and Time Specification of RFC 822.

If you load an OPML document into your client, you may choose to respect expansionState, or not. We’re not in any way trying to dictate user experience. The expansionState info is there because it’s needed in certain contexts. It’s easy to imagine contexts where it would make sense to completely ignore it.

What is a <body>?

A <body> contains one or more <outline> elements.

What is an <outline>?

An <outline> is an XML element, possibly containing one or more attributes, and containing any number of <outline> sub-elements.

Common attributes

text is the string of characters that’s displayed when the outline is being browsed or edited. There is no specific limit on the length of the text attribute.

type is a string, it says how the other attributes of the <outline> are interpreted.

isComment is a string, either “true” or “false”, indicating whether the outline is commented or not. By convention if an outline is commented, all subordinate outlines are considered to be commented as well. If it’s not present, the value is false.

isBreakpoint is a string, either “true” or “false”, indicating whether a breakpoint is set on this outline. This attribute is mainly necessary for outlines used to edit scripts that execute. If it’s not present, the value is false.

Compatibility

Before the 1.0 format was frozen the top-level element of the format was called outlineDocument. Radio UserLand will continue to read such documents.

Limits

There are no documented limits to the number of attributes an <outline> element can have, or the number of <outline> elements it can contain.

Notes

OPML is a file format, not a protocol. When you click on a link in an HTML document it doesn’t in any way change the document stored on the server. OPML is used in much the same way.

Wayne Steele did a DTD for OPML 1.0. Thank you.

In general, the mimetype for an OPML document, when accessed over HTTP, is text/xml. This allows Web browsers to use XML formatting conventions to display an OPML document. Radio UserLand’s built-in HTTP server looks at the Accept header of the request to determine how it processes an OPML document. If the Accept header says that the client understands text/x-opml, we return the unprocessed XML text. If it is not present, we return the text in the outline with the mimetype text/html.