XML: Services Lists
This documentation outlines the principles and format behind the
service lists that we keep for myChannels.opml, myStrips.opml and
myWebCams.opml. As per the myServices
document, the format closely resembles Dave Winer's Userland
format, but OCS has been
taken into consideration as well.
There are three kinds of services lists available for each type of service:
- The "complete" list is every service
still operational - we don't check for validity, we don't check
for freshness, we don't check for content - we only check if it's
there. For the channels service list, this file would be called
services-channels-complete.xml.
- The "recent" list is a paired down version of
the "complete" list, and contains services updated in the past
month. For the channels service list, this file would be called
services-channels-recent.xml.
- Finally, the "failure" list are services
that 404'd or host unreachable, had internal server errors, or were
otherwise not valid XML. For the channels service list, this file
would be called services-channels-failure.xml.
A complete (yet rather minimal) service is shown below.
<?xml version='1' standalone='yes'?>
<servicelist>
<header>
<docs>http://www.disobey.com/amphetadesk/xml_services_lists.htm</docs>
<entries>1255</entries>
<updated>Thu, 15 Mar 2001 00:10:39 GMT</updated>
<version>1</version>
</header>
<services>
<service>
<description>The best little example description around!</description>
<error>No headers downloaded.</error>
<htmlurl>http://www.superlugnuts.com/example.html</htmlurl>
<id>f3cc9706db585cd9b776ae143897106b</id>
<imageurl>http://www.superlugnuts.com/image.jpg</imageurl>
<language>en</language>
<lastchecked>Mon, 05 Mar 2001 14:32:37 GMT</lastchecked>
<lastmodified>Thu, 08 Jun 2000 13:40:05 GMT</lastmodified>
<timeschecked>2</timeschecked>
<title>Super LugNuts and Happy Examples</title>
<xmlurl>http://www.superlugnuts.com/example.xml</xmlurl>
</service>
</services>
</servicelist>
|
You can see how this would show up if a user subscribed to it by checking out the myServices documentation.
<description>
Allowed Within: <service>
Frequency: Once
Required: No
The <description> element is determined by the actual service
and can be a string of any length. Most of the time, the service
author will put a little blurb about the service - other authors
will put the last modified date of the service.
|
<docs>
Allowed Within: <header>
Frequency: Once
Required: Yes
<docs> points to a valid URI explaining what all this means.
|
<entries>
Allowed Within: <header>
Frequency: Once
Required: Yes
<entries> remarks the total number of services within the list.
|
<error>
Allowed Within: <service>
Frequency: Once
Required: No
<error> is only used within the failure lists and represents
a short, simple, generic message for why the service is considered
a failure. Current applicable values are "No headers downloaded"
(common when the service host has timed out on responding, or
when the service host is unavailable) and "Error parsing XML"
(common due to custom 404 pages, redirects to home pages, or
when the data isn't valid XML).
|
<header>
Allowed Within: <servicelist>
Frequency: Once
Required: Yes
The <header> block portrays some housecleaning and administrative
information, such as <docs> (where to go
for more information), <entries> (how
many services are in the list), <updated>
(when the service list was updated), and <version>
(what evolution this service list is at).
|
<htmlurl>
Allowed Within: <service>
Frequency: Once
Required: No
See Also: <imageurl>, <xmlurl>
Convincingly enough, the <htmlurl> attribute contains the full
URI to the webpage of the service in question.
|
<id>
Allowed Within: <service>
Frequency: Once
Required: Yes
<id> is a unique identifier for the service and is a 32
character md5 hash of the xmlurl (the xmlurl is just a seed, and
shouldn't be given any importance - in myStrips.opml and myWebCams.opml,
you'd use the imageurl).
|
<imageurl>
Allowed Within: <service>
Frequency: Once
Required: Yes (myWebCams.opml, myStrips.opml); No (myChannels.opml)
See Also: <htmlurl>, <xmlurl>
Although <imageurl> sounds easy enough, there is a bit of
confusion concerning what exactly it means in different contexts.
In myChannels.opml, it means nothing, and you'll never see it.
If, on the other hand, you're messing with myStrips.opml
and myWebCams.opml, the <imageurl> points to the URI of the comic
strip or webcam image in question.
|
<language>
Allowed Within: <service>
Frequency: Once
Required: No
<language> holds the dialect that the service is published in.
This is currently ignored, but that may change in the future
(perhaps a filter by language? auto creation of urls for net
translators? any other suggestions?). Examples of valid languages:
"en", "en-us", "fr", etc.
|
<lastchecked>
Allowed Within: <service>
Frequency: Once
Required: No
See Also: <timeschecked>
<lastchecked> tells us when the last time the service entry was
checked for information - whether it be for existence, title and
description, or just for the last modification date.
|
<lastmodified>
Allowed Within: <service>
Frequency: Once
Required: No
If the webserver reports a "Last-Modified:" field in the
response request of the service, we insert that value in this
element. Typically, the results are in GMT. Not all servers
implement the "Last-Modified:" response, so we can't rely
on it as being an adequate measure of service age.
|
<service>
Allowed Within: <services>
Frequency: Multiple
Required: Yes
The <service> tag contains one service definition. There can
be an unlimited number of services in a single file.
|
<timeschecked>
Allowed Within: <service>
Frequency: Once
Required: No
See Also: <lastchecked>
Much like <lastchecked> tells
us when we last looked at the service for data, <timeschecked>
measures how often we have looked at the service. This can be used
to make determinations on failed services, or just as a measure of
longevity in the service list.
|
<title>
Allowed Within: <service>
Frequency: Once
Required: Yes
<title> showcases the title or name of the service in question and can be any length.
|
<updated>
Allowed Within: <header>
Frequency: Once
Required: Yes
The last time the list was updated, in GMT.
|
<xmlurl>
Allowed Within: <service>
Frequency: Once
Required: Yes (myChannels.opml); No (myWebCams.opml, myStrips.opml)
See Also: <htmlurl>, <imageurl>
<xmlurl> is the full URI to the document that contains the
channel xml. It's ignored for myStrips.opml and myWebCams.opml.
|
<version>
Allowed Within: <header>
Frequency: Once
Required: Yes
The <version> tag allows us to track different
variations of the service list in question - the current version is "1".
|
Any questions about the above? Email morbus@disobey.com.
This footer was last updated 3/14/01; odds are the whole document was too.
|