Open Publication Distribution System

A Primer

Contents

Overview

OPDS Primer

Comments

 

Related Links

OPDS Spec

Atom Format

AtomPub

Web linking

Status of this document

This is an introduction to the Open Publishing Distribution System Catalog 1.0 specification. This document is informative rather than normative. When this document disagrees, if ever, with the OPDS Catalog specification, please refer to the spec.

What are OPDS Catalogs?

OPDS Catalogs enable the aggregation, distribution, and discovery of books, journals, and other digital content by any user, from any source, in any electronic format, on any device. The OPDS Catalogs specification is based on the Atom syndication format and prioritizes simplicity and speed.

The OPDS Catalog specification is continually in development, so any ideas, suggestions, or feedback are welcomed on our dedicated group.

Feeds & Entries

OPDS catalogs borrow the concept of feeds and entries defined in the Atom syndication format (Atom Spec) :

Atom is an XML-based document format that describes lists of related information known as "feeds". Feeds are composed of a number of items, known as "entries", each with an extensible set of attached metadata. For example, each entry has a title.

A feed is essentially a container for entries and when consuming Atom you can either encounter a feed or a single entry.

In an OPDS catalog, we define two different uses for feeds:

  1. Navigation feeds, used by a client to navigate through the catalog
  2. Acquisition feeds, where publications are listed and can be acquired

Both feeds are valid Atom feeds and can be consumed by a generic Atom client.

Catalog producers are expected to separate navigation feeds from acquisition feeds: a feed can't be both at the same time.

In a similar fashion, entries in OPDS can either be:

  1. Catalog links, pointing to another feed and used in Navigation feeds
  2. Publications, listing various metadata and providing an acquisition link in an Acquisition feed

Publications are identified by the presence of an acquisition link. The lack of such link indicates that an entry is a catalog link.

An Acquisition link is a link to a resource that you can acquire.

In Atom, it's basically a link tag using a relationship (a rel attribute) starting with “http://opds-spec.org/acquisition”.

OPDS provides predefined relationships for various acquisition scenarios:

A Generic Acquisition relation is also available when the acquisition doesn't fit in any of the acquisition scenarios.

The associated rel values are:

Acquisition Scenario rel attribute value
Generic Acquisition http://opds-spec.org/acquisition
Open Access http://opds-spec.org/acquisition/open-access
Sale http://opds-spec.org/acquisition/buy
Lending http://opds-spec.org/acquisition/borrow
Subscription http://opds-spec.org/acquisition/subscribe
Sampling http://opds-spec.org/acquisition/sample

Full Entries

Catalog producers are encouraged to provide extensive metadata and links in their publications’ entries. To avoid bandwidth and speed issues,  OPDS recommends a feature first introduced in AtomPub: full entries.

Any publication can point to a separate document, where the entry is redefined with additional elements using a link tag with the following attributes: rel="alternate" and type="application/atom+xml;type=entry".


  <entry>
    <title>On the Origin of Species</title>
    <id>http://www.example.com/42</id>
    <author>
      <name>Charles Darwin</name>
    </author>
    <updated>2010-01-02T15:27:07Z</updated>
    <link type="application/epub+zip"
             href="http://www.example.com/42.epub" rel="http://opds-spec.org/acquisition/open-access"/>
    <link type="application/atom+xml;type=entry" 
             href="http://www.example.com/42.atom" rel="alternate" title="Full entry"/>
  </entry>

Partial entry example.

The most common use case for full entries is for publication with an extensive description. The partial entry can provide a shorter description in its summary element, while the full entry contains the complete description in a content element.

Full entries also provide a simple extension mechanism for OPDS, where catalogs can use metadata and link relationships that are specific to a given domain.

Aside from navigating through a series of navigation feeds, a client can also access publications through a search.

Search in OPDS is based on the Open Search format, where a separate document called an Open Search Description Document describes how a client can search in the catalog.

Search is an optional OPDS feature.

Examples

Bob would like to get a new book and uses an OPDS enabled device.

He points it to an OPDS catalog and gets a list of the different sections available.

This catalog is a Navigation Feed

He chooses a section, called for example “Scientific books”, and gets a list of available publications.

This list is an Acquisition Feed. The title list is created by getting all the title elements in the publication list

He would like to see if one of the book (On the Origin of Species) has a summary. He selects it and his client provides him with a summary, the publication date and a link to user reviews of this book.

When Bob selected the publication the reading system looked for a full entry link, retrieved it and presented its content to Bob.

After reading the summary Bob decides to acquire the book and clicks on the download button.

The acquisition link provided the address where the client can download the book.

This first scenario describes a common usage of OPDS. Here are some more advanced uses.

Before getting the Acquisition Feed Bob could traverse any number of Navigation Feeds. For example : Books > Scientific Books > XIX century Books > High School Classics (Each ‘>’ indicates a link followed)

OPDS catalogs can be viewed as trees where the leaves are Acquisition Feeds

Maybe Bob didn't want to discover new books to read, maybe he only wanted to read On the Origin of Species. He points the client to the catalog and uses the search facility and type in “the origin of species”. He is directly provided with matches from the catalog provider On the Origin of Species,Species of the Origin, Original spätzel cooking. He then only has to choose the desired book and acquires it.

In this example, the client uses an Open Search Description Document to look for potential matches. The Catalog provider responds to the query directly with an Acquisition feed.

This particular edition of On the Origin of Species might not be available freely. The catalog provider could use a Buy relationship and indicate a price for it in the link. Upon choosing to acquire this book Bob would have been asked to give due payment before getting the desired content.

Multiple acquisition links can be provided in publications’ entries. The catalog provider could also have offered a second link with the Sample relationship pointing to a sample chapter from the book.

Autodiscovery

OPDS Catalog can be automatically discovered by clients. Simply set a link tag with type=”application/atom+xml;profile=opds-catalog” attribute. More mechanisms are detailed in the spec.

Autodiscovery is an optional OPDS feature.

Crawling feeds

Sometimes clients may wish to get all the data about publications. OPDS workgroup is aware of this potential issue and recommends that publishers provide dedicated crawlable feeds.

Crawler optimized feed is an optional OPDS feature.

Getting Started

Feedbooks provide an OPDS catalog at: http://www.feedbooks.com/catalog

Take a look at our feeds and entries for more advanced examples of what you can do with OPDS.

To test your own catalog, take a look at our list of reading systems connected to the Feedbooks catalog.