This document specifies version 1.0 of the OPDS Catalog specification.
Published: 30 August 2010
This document is licensed under Creative Commons Attribution-Share Alike.
The Open Publication Distribution System (OPDS) Catalog format is a syndication format for electronic publications based on Atom and HTTP. OPDS Catalogs enable the aggregation, distribution, discovery, and acquisition of electronic publications. OPDS Catalogs use existing or emergent open standards and conventions, with a priority on simplicity.
The Open Publication Distribution System (OPDS) Catalog format is a syndication format for electronic publications based on Atom [RFC4287] and HTTP [RFC2616]. OPDS Catalogs enable available electronic publications to be:
An OPDS Catalog is a set of one or more Atom Feeds, which are themselves listings of Atom Entries. The Atom Feeds that make up all OPDS Catalogs can be divided into two groups: Navigation Feeds, which create a hierarchy for browsing, and Acquisition Feeds, which list available electronic publications. Each Atom Entry in an Acquisition Feed includes basic metadata about the publication, the publication's format, and how the publication can be acquired. These included Atom Entries may be minimal subsets of the complete metadata, with a link to a more extensive, standalone representation URI (see the Section Listing Acquisition Feeds for more).
OPDS Catalogs may be aggregated and combined into larger OPDS Catalogs.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
The OPDS Catalog format is specified in terms of the XML Information Set [REC-xml-infoset], serialized as XML 1.0 [REC-xml].
The Infoset terms "Element Information Item" and "Attribute Information Item" are shortened to "element" and "attribute" respectively. Therefore, when this specification uses the term "element", it is referring to an Element Information Item, and when it uses the term "attribute", it is referring to an Attribute Information Item.
Some sections of this specification are illustrated with fragments of a non-normative RELAX NG Compact schema [RNC]. However, the text of this specification provides the definition of conformance. Complete schemas appear in Appendix B.
The following terminology is used by this specification:
This specification defines two kinds of documents -- OPDS Catalog Feed Documents and OPDS Catalog Entry Documents.
An OPDS Catalog Feed Document is a refinement of an "atom:feed" from the Atom Syndication Format [RFC4287].
An OPDS Catalog Entry Document is a refinement of an "atom:entry" from the Atom Syndication Format [RFC4287].
The namespace name [REC-xml-names] for elements defined in this specification and used in OPDS Catalog Feed Documents and OPDS Catalog Entry Documents is:
http://opds-spec.org/2010/catalog
OPDS Catalog Feed Documents and OPDS Catalog Entry Documents MUST be "namespace-well-formed" as specified in Section 7 of [REC-xml-names].
This specification uses the prefix "opds:" for the namespace name. The prefix "atom:" is used for "http://www.w3.org/2005/Atom ", the namespace name of the Atom Syndication Format [RFC4287]. The prefix "dc:" is used for"http://purl.org/dc/terms/", the namespace name of Dublin Core Metadata Initiative (DCMI) Metadata Terms [DCTERMS]. These namespace prefixes are not semantically significant.
Producers of OPDS Catalogs SHOULD produce OPDS Catalog Feed Documents and OPDS Catalog Entry Documents that are conformant to both Atom and the OPDS Catalog RELAX NG schemas.
Unrecognized markup in any Atom Feed or Atom Entry in an OPDS Catalog is considered "foreign markup" as defined in Section 6 of the Atom Syndication Format [RFC4287]. Foreign markup can be used anywhere within an OPDS Catalog unless it is explicitly forbidden. Processors that encounter foreign markup MUST NOT stop processing and MUST NOT signal an error. Clients SHOULD preserve foreign markup when transmitting or aggregating such documents.
The namespace name "http://opds-spec.org/2010/catalog" is reserved for forward-compatible revisions of the OPDS Catalog format. This does not exclude the addition of elements and attributes that might not be recognized by processors conformant to this specification. Such unrecognized markup from the "http://opds-spec.org/2010/catalog" namespace MUST be treated as foreign markup.
OPDS Catalog Feed Documents are Atom [RFC4287] Feeds. They serve two purposes:
While Navigation Feeds do provide a suggested hierarchy from the OPDS Catalog publisher, OPDS Catalog Feed Documents MAY contain other relations that allow for other methods of consumption and display. See the Section OPDS Catalog Relations for more detail.
Every OPDS Catalog Feed Document MUST either be an Acquisition Feed or a Navigation Feed. An Acquisition Feed can be identified by the presence of Acquisition Links in each Atom Entry.
The OPDS Catalog Root is the top-level OPDS Catalog Feed Document. It is either a single Acquisition Feed in the simple case or the start of a set of Navigation Feeds. Every OPDS Catalog MUST have one and only one OPDS Catalog Root.
External links to the OPDS Catalog Resource SHOULD use the IRI of the OPDS Catalog Root.
Each OPDS Catalog Feed Document SHOULD contain an atom:link element with a link relation of "start", which references the OPDS Catalog Root Resource.
An Acquisition Feed is an OPDS Catalog Feed Document that collects OPDS Catalog Entries into a single, ordered set. The simplest complete OPDS Catalog would be a single Acquisition Feed listing all of the available OPDS Catalog Entries from that provider. In more complex OPDS Catalogs, Acquisition Feeds are used to present and organize sets of related OPDS Catalog Entries for browsing and discovery by clients and aggregators.
Links to Acquisition Feeds SHOULD use the "type" attribute "application/atom+xml;profile=opds-catalog".
For further details on limiting the size of Acquisition Feeds through pagination, Partial Catalog Entries, and compression, see the Section Listing Acquisition Feeds.
OPDS Catalog Feed Documents SHOULD include links to other available Acquisition and Navigation Feeds and other related Resources to encourage independent navigation.
These relations MAY be used by clients to provide additional or alternative navigation, both in a Navigation Feed or an Acquisition Feed.
The following relations are derived from [DRAFT-Web-Linking], with some clarification:
When creating an OPDS Catalog with Navigation and Acquisition Feeds, OPDS Catalog providers are encouraged to use the relations defined in this specification and [DRAFT-Web-Linking]. If no appropriate relation is found, the Feeds SHOULD use a descriptive "atom:title" element and the "atom:link"s SHOULD use a descriptive "title" attribute.
This specification defines two new relations, which begin with "http://opds-spec.org/sort", to describe how an Acquisition Feed is sorted. These relations SHOULD be used when creating Navigation Feeds and the OPDS Catalog Root, if applicable.
Acquisition Feeds using the "http://opds-spec.org/sort/new" relation SHOULD be ordered with the most recent items first. Acquisition Feeds using the "http://opds-spec.org/sort/popular" relation SHOULD be ordered with the most popular items first.
This specification also defines a relation to describe an Acquisition Feed of featured items. This relation SHOULD be used when creating Navigation Feeds and the OPDS Catalog Root, if applicable.
An OPDS catalog MAY track content that was previously acquired by the user. This specification defines two new relations to identify Acquisition Feeds listing such resources:
An OPDS client MAY use these links to automatically sync content to the user's local shelf or check for periodical content updates.
For aggregation or crawling purposes, an OPDS Catalog MAY link to an optimized Acquisition Feed. This specification defines one new relation for this goal: "http://opds-spec.org/crawlable".
See Complete Acquisition Feeds for more information about this feed.
An OPDS Catalog MAY provide a search facility through an [OpenSearch] description document. Links to [OpenSearch] description documents MUST use the "search" relation value and the "application/opensearchdescription+xml" media type as defined in the "Autodiscovery" section of the [OpenSearch] specification.
<link rel="search"
href="search.xml"
type="application/opensearchdescription+xml"/>
In an [OpenSearch] description document, the search interface SHOULD use the media type associated to OPDS Catalogs:
<Url type="application/atom+xml;profile=opds-catalog"
template="http://example.com/search?q={searchTerms}" />
OPDS Catalog Feed Documents MAY include elements from the [OpenSearch] namespace such as "opensearch:totalResults" or "opensearch:itemsPerPage" in [OpenSearch] responses.
An OPDS Catalog Root that is the top of a set of Navigation Feeds references three Acquisition Feeds using atom:links:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<id>urn:uuid:2853dacf-ed79-42f5-8e8a-a7bb3d1ae6a2</id>
<link rel="self"
href="/opds-catalogs/root.xml"
type="application/atom+xml;profile=opds-catalog"/>
<link rel="start"
href="/opds-catalogs/root.xml"
type="application/atom+xml;profile=opds-catalog"/>
<title>OPDS Catalog Root Example</title>
<updated>2010-01-10T10:03:10Z</updated>
<author>
<name>Spec Writer</name>
<uri>http://opds-spec.org</uri>
</author>
<entry>
<title>Popular Publications</title>
<link rel="http://opds-spec.org/sort/popular"
href="/opds-catalogs/popular.xml"
type="application/atom+xml;profile=opds-catalog"/>
<updated>2010-01-10T10:01:01Z</updated>
<id>urn:uuid:d49e8018-a0e0-499e-9423-7c175fa0c56e</id>
<content type="text">Popular publications from this catalog based
on downloads.</content>
</entry>
<entry>
<title>New Publications</title>
<link rel="http://opds-spec.org/sort/new"
href="/opds-catalogs/new.xml"
type="application/atom+xml;profile=opds-catalog"/>
<updated>2010-01-10T10:02:00Z</updated>
<id>urn:uuid:d49e8018-a0e0-499e-9423-7c175fa0c56c</id>
<content type="text">Recent publications from this catalog.</content>
</entry>
<entry>
<title>Unpopular Publications</title>
<link rel="subsection"
href="/opds-catalogs/unpopular.xml"
type="application/atom+xml;profile=opds-catalog"/>
<updated>2010-01-10T10:01:00Z</updated>
<id>urn:uuid:d49e8018-a0e0-499e-9423-7c175fa0c56d</id>
<content type="text">Publications that could use some love.</content>
</entry>
</feed>
An Acquisition Feed listing OPDS Catalog Entries from the "Unpopular Publications" Entry in the Navigation Feed above:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:opds="http://opds-spec.org/2010/catalog">
<id>urn:uuid:433a5d6a-0b8c-4933-af65-4ca4f02763eb</id>
<link rel="related"
href="/opds-catalogs/vampire.farming.xml"
type="application/atom+xml;profile=opds-catalog"/>
<link rel="self"
href="/opds-catalogs/unpopular.xml"
type="application/atom+xml;profile=opds-catalog"/>
<link rel="start"
href="/opds-catalogs/root.xml"
type="application/atom+xml;profile=opds-catalog"/>
<link rel="up"
href="/opds-catalogs/root.xml"
type="application/atom+xml;profile=opds-catalog"/>
<title>Unpopular Publications</title>
<updated>2010-01-10T10:01:11Z</updated>
<author>
<name>Spec Writer</name>
<uri>http://opds-spec.org</uri>
</author>
<entry>
<title>Bob, Son of Bob</title>
<id>urn:uuid:6409a00b-7bf2-405e-826c-3fdff0fd0734</id>
<updated>2010-01-10T10:01:11Z</updated>
<author>
<name>Bob the Recursive</name>
<uri>http://opds-spec.org/authors/1285</uri>
</author>
<dc:language>en</dc:language>
<dc:issued>1917</dc:issued>
<category scheme="http://www.bisg.org/standards/bisac_subject/index.html"
term="FIC020000"
label="FICTION / Men's Adventure"/>
<summary>The story of the son of the Bob and the gallant part
he played in the lives of a man and a woman.</summary>
<link rel="http://opds-spec.org/image"
href="/covers/4561.lrg.png"
type="image/png"/>
<link rel="http://opds-spec.org/image/thumbnail"
href="/covers/4561.thmb.gif"
type="image/gif"/>
<link rel="alternate"
href="/opds-catalogs/entries/4571.complete.xml"
type="application/atom+xml;type=entry;profile=opds-catalog"
title="Complete Catalog Entry for Bob, Son of Bob"/>
<link rel="http://opds-spec.org/acquisition"
href="/content/free/4561.epub"
type="application/epub+zip"/>
<link rel="http://opds-spec.org/acquisition"
href="/content/free/4561.mobi"
type="application/x-mobipocket-ebook"/>
</entry>
<entry>
<title>Modern Online Philately</title>
<id>urn:uuid:7b595b0c-e15c-4755-bf9a-b7019f5c1dab</id>
<author>
<name>Stampy McGee</name>
<uri>http://opds-spec.org/authors/21285</uri>
</author>
<author>
<name>Alice McGee</name>
<uri>http://opds-spec.org/authors/21284</uri>
</author>
<author>
<name>Harold McGee</name>
<uri>http://opds-spec.org/authors/21283</uri>
</author>
<updated>2010-01-10T10:01:10Z</updated>
<rights>Copyright (c) 2009, Stampy McGee</rights>
<dc:identifier>urn:isbn:978029536341X</dc:identifier>
<dc:publisher>StampMeOnline, Inc.</dc:publisher>
<dc:language>en</dc:language>
<dc:issued>2009-10-01</dc:issued>
<content type="text">The definitive reference for the web-curious
philatelist.</content>
<link rel="http://opds-spec.org/image"
href="/covers/11241.lrg.jpg"
type="image/jpeg"/>
<link rel="http://opds-spec.org/acquisition/buy"
href="/content/buy/11241.epub"
type="application/epub+zip">
<opds:price currencycode="USD">18.99</opds:price>
<opds:price currencycode="GBP">11.99</opds:price>
</link>
</entry>
</feed>
The "atom:feed" element is the document (i.e., top-level) element of an OPDS Catalog Feed Document, acting as a container for metadata, hierarchy, and Publications associated with the OPDS Catalog. Its element children consist of metadata elements followed by zero or more atom:entry child elements.
The following child elements are refined by this specification:
OPDS Catalog Entry Documents are Atom [RFC4287] Entry documents that provide a complete representation of the metadata and data associated with an available Publication.
Each OPDS Catalog Entry Document MUST include at least one Acquisition Link, which is an atom:link element with a relation that begins "http://opds-spec.org/acquisition". This link refers to the Resource which is the content of the Resource described by the OPDS Catalog Entry in a particular media type. Acquisition Links use one of the relations described in the Section Acquisition Relations.
OPDS Catalog providers are encouraged to include metadata from the Dublin Core Metadata Initiative (DCMI) Metadata Terms [DCTERMS] whenever appropriate. However, these elements are not required. Some of the elements defined in [DCTERMS] overlap in meaning with similar elements defined by Atom in [RFC4287]. In general, OPDS Catalog Entries prefer the Atom elements over the [DCTERMS] elements and the following rules should be used by OPDS Catalog providers when choosing elements:
All metadata elements required by Atom are required in OPDS Catalog Entries and Feeds.
Following Atom [RFC4287] Section 4.2.6, the content of an "atom:id" identifying an OPDS Catalog Entry MUST NOT change when the OPDS Catalog Entry is "relocated, migrated, syndicated, republished, exported, or imported" and "MUST be created in a way that assures uniqueness."
An OPDS Catalog Entry may be represented as either a Partial or Complete Catalog Entry. Partial Catalog Entries include only critical metadata elements to reduce the size of OPDS Catalog documents for bandwidth- and resource-limited clients and link to their alternate representation as a Complete Catalog Entries, which include all metadata elements.
A Partial Catalog Entry MUST include an "alternate" link relation referencing the Complete Catalog Entry Resource and that atom:link MUST use the "type" attribute "application/atom+xml;type=entry;profile=opds-catalog".
Any OPDS Catalog Entry without a link to a Complete Catalog Entry MUST include all metadata elements.
Partial Catalog Entries SHOULD include the following metadata elements, if available:
OPDS Catalog providers are strongly encouraged to limit metadata elements not required by Atom, OPDS, or listed above from Partial Catalog Entries to help facilitate the efficient transmission and consumption of OPDS Catalog documents. Implementers are encouraged to include metadata elements from other vocabularies in Complete Catalog Entries.
OPDS Catalog Entries use "atom:content" and "atom:summary" elements to describe a Publication. This is a distinction from Atom [RFC4287], which uses "atom:content" for the "content of the entry." Instead, OPDS Catalog Entries reference an electronic document with the Publication's content using Acquisition Links. OPDS Catalog Entries SHOULD include either "atom:summary" or "atom:content" elements or both to provide a description, summary, abstract, or excerpt of the Publication.
An "atom:summary" element in an OPDS Catalog Entry MUST use a "type" attribute of "text" and the content MUST NOT contain child elements. The content of an "atom:summary" element SHOULD NOT duplicate the content of "atom:title" or "atom:content". Such text is intended to be presented to humans in a readable fashion. The restriction of the content of "atom:summary" and the "type" attribute is a restriction of Atom [RFC4287].
An "atom:content" element in an OPDS Catalog Entry either contains or links to a description, summary, abstract, or excerpt of the Publication. The behavior or "atomOutOfLineContent" and the "src" attribute is defined in Section 4.1.3 of [RFC4287].
If an OPDS Catalog Entry includes both "atom:content" and "atom:summary", the "atom:content" SHOULD NOT be included in the Partial Catalog Entry. Both elements SHOULD be included in the Complete Catalog Entry.
atomSummary =
element atom:summary {
atomCommonAttributes,
attribute type { "text" }?,
text
}
OPDS Catalog Entry Documents SHOULD include links to related Resources. This specification defines new relations for linking from OPDS Catalog Entry Documents. They are defined in the Sections Acquisition Relations and Artwork Relations.
OPDS Catalog providers are encouraged to use relations from [DRAFT-Web-Linking] inside OPDS Catalog Entry Documents where appropriate.
Acquisition relations describe the extent of the content referred to by an Acquisition Link or the manner in which that Resource may be acquired. This specification defines six Acquisition Relations, which all begin with "http://opds-spec.org/acquisition":
OPDS Catalog Entries MAY include atom:links to images that provide a visual representation of the Publication. For many Publications, these images will be the Publication's artwork. This specification defines two Artwork Relations, which begin with "http://opds-spec.org/image":
Image resources related by http://opds-spec.org/image/thumbnail SHOULD be suitable for presentation at a small size.
The atom:links with these relations SHOULD include at least one link with a type attribute of "image/gif", "image/jpeg", or "image/png" and the image Resources MUST be in GIF, JPEG, or PNG format.
Additional atom:links MAY also include additional resources using a vector-based format.
While either image Resource is optional and may be included independently, OPDS Catalog providers are encouraged to provide both these relations and Resources whenever possible.
Some OPDS Catalog providers MAY choose to provide http://opds-spec.org/image/thumbnail image Resources using the "data" URL scheme from [RFC2397]. OPDS Catalog clients SHOULD support the "data" URL scheme if they support Artwork relations.
An example of a Partial Catalog Entry (as would appear in an Acquisition Feed) for a Publication available in two formats:
<entry>
<title>Bob, Son of Bob</title>
<id>urn:uuid:6409a00b-7bf2-405e-826c-3fdff0fd0734</id>
<updated>2010-01-10T10:01:11Z</updated>
<author>
<name>Bob the Recursive</name>
<uri>http://opds-spec.org/authors/1285</uri>
</author>
<dc:language>en</dc:language>
<dc:issued>1917</dc:issued>
<category scheme="http://www.bisg.org/standards/bisac_subject/index.html"
term="FIC020000"
label="FICTION / Men's Adventure"/>
<summary type="text">The story of the son of the Bob and the gallant part
he played in the lives of a man and a woman.</summary>
<link rel="http://opds-spec.org/image"
href="/covers/4561.lrg.png"
type="image/png"/>
<link rel="http://opds-spec.org/image/thumbnail"
href="/covers/4561.thmb.gif"
type="image/gif"/>
<link rel="alternate"
href="/opds-catalogs/entries/4571.complete.xml"
type="application/atom+xml;type=entry;profile=opds-catalog"
title="Complete Catalog Entry for Bob, Son of Bob"/>
<link rel="http://opds-spec.org/acquisition"
href="/content/free/4561.epub"
type="application/epub+zip"/>
<link rel="http://opds-spec.org/acquisition"
href="/content/free/4561.mobi"
type="application/x-mobipocket-ebook"/>
</entry>
The Complete Catalog Entry for the same Publication:
<entry>
<title>Bob, Son of Bob</title>
<id>urn:uuid:6409a00b-7bf2-405e-826c-3fdff0fd0734</id>
<updated>2010-01-10T10:01:11Z</updated>
<author>
<name>Bob the Recursive</name>
<uri>http://opds-spec.org/authors/1285</uri>
</author>
<dc:language>en</dc:language>
<dc:issued>1917</dc:issued>
<category scheme="http://www.bisg.org/standards/bisac_subject/index.html"
term="FIC020000"
label="FICTION / Men's Adventure"/>
<summary type="text">The story of the son of the Bob and the gallant part
he played in the lives of a man and a woman.</summary>
<content type="text">The story of the son of the Bob and the gallant part
he played in the lives of a man and a woman. Bob begins his humble life
under the wandering eye of his senile mother, but quickly learns how to
escape into the wilder world. Follow Bob as he uncovers his father's past
and uses those lessons to improve the lives of others.</content>
<link rel="http://opds-spec.org/image"
href="/covers/4561.lrg.png"
type="image/png"/>
<link rel="http://opds-spec.org/image/thumbnail"
href="/covers/4561.thmb.gif"
type="image/gif"/>
<link rel="self"
href="/opds-catalogs/entries/4571.complete.xml"
type="application/atom+xml;type=entry;profile=opds-catalog"/>
<link rel="http://opds-spec.org/acquisition"
href="/content/free/4561.epub"
type="application/epub+zip"/>
<link rel="http://opds-spec.org/acquisition"
href="/content/free/4561.mobi"
type="application/x-mobipocket-ebook"/>
</entry>
The "atom:entry" element is the document (i.e., top-level) element of an OPDS Catalog Entry Document, acting as a container for metadata and data associated with an available Publication.
The following child elements are refined by this specification:
The "atom:link" element defines a reference from an Atom Entry or Atom Feed to a Resource.
atomLink =
element atom:link {
atomCommonAttributes &
attribute href { atomUri } &
attribute type { atomMediaType }? &
attribute hreflang { atomLanguageTag }? &
attribute title { text }? &
attribute length { text }? &
((attribute rel { "http://opds-spec.org/acquisition/buy" }, opdsPrice+ )
|
(attribute rel { OPDSUrisExceptBuy }, opdsPrice*)
|
(attribute rel { atomNCName | ( atomUriExceptOPDS ) } ))? &
anyOPDSForeignElement* &
text
}
# Here is where OPDS Catalogs use John Cowan's pragmatic evaluation of an
# IRI. This modifies xsd:anyURI in XSD 1.0 to exclude ASCII characters not
# valid in 1.1 or IRI's without being escaped. This matches the OPDS and Atom
# specs, but not the non-normative atom.rnc.
atomUri = xsd:anyURI - xsd:string {pattern = '.*[ <>{}|^`"\\\n\r\t].*'}
The following child elements are defined by this specification:
The "opds:price" element represents the acquisition price in a particular currency of an individual Publication in a particular format from a particular provider. This element can appear as a child of the atom:link element (in OPDS Catalog Entry Documents).
The content of opds:price is text describing a currency value. A currency sign MUST NOT be included.
opdsPrice =
element opds:price {
atomCommonAttributes,
attribute currencycode { opdsPriceCurrencyCode },
xsd:decimal { minInclusive="0.0" }
}
On the opds:price element, the value of the "currencycode" attribute MUST be an active code from [ISO4217] representing a currency. It defines the currency used for the content of the opds:price element.
The goal of OPDS Catalogs is to make Publications both discoverable and straightforward to acquire on a range of devices and platforms. To support that goal, this specification strives to provide a framework for describing how a Publication may be acquired while not attempting to constrain this very complex topic. Commonly-used acquisition scenarios may be specified in an update to this specification.
All Acquisition Links MUST include a "type" attribute that advises clients on the media type of the representation that is expected to be returned when the value of the href attribute is dereferenced. As with Atom, the value of the type attribute MUST conform to the syntax of a MIME media type [MIMEREG].
Publications in a format using Digital Rights Management SHOULD use a different value for the type attribute of the Acquisition Link than the same format without Digital Rights Management.
OPDS Catalog clients may only support a subset of all possible Publication media types. These clients will need to filter both the type attribute of Acquisition Links.
The simplest case is a Publication available in one format:
<link rel="http://opds-spec.org/acquisition"
type="video/mp4v-es"
href="/content/free/4561.mp4"/>
If the Publication was available in multiple formats as unique Resources, they would simply be listed:
<link rel="http://opds-spec.org/acquisition/borrow"
href="/content/borrow/4561.mobi"
type="application/x-mobipocket-ebook"/>
<link rel="http://opds-spec.org/acquisition/borrow"
href="/content/borrow/4561.epub"
type="application/epub+zip"/>
If the Publication requires payment, at least one opds:price element is required:
<link rel="http://opds-spec.org/acquisition/buy"
href="/product/song1.mp3"
type="audio/mpeg">
<opds:price currencycode="USD">1.99</opds:price>
</link>
OPDS Catalog Feed Documents, especially Acquisition Feeds, may contain large numbers of Atom Entries.
A client such as a web spider or web browser might be overwhelmed if the response to a GET contained every Atom Entry in an Acquisition Feed -- in turn the server might also waste bandwidth and processing time on generating a response that cannot be handled. For this reason, servers MAY respond to Acquisition Feed GET requests with a paginated response: an OPDS Catalog Feed Document containing a partial list of the Acquisition Feed's member Atom Entries and a link to the next partial Acquisition Feed, if it exists, as defined in Section 3 of [RFC5005].
OPDS Catalog providers SHOULD use Partial Catalog Entries in all Acquisition Feeds except Complete Acquisition Feeds, which are intended for crawling and are referenced using the http://opds-spec.org/crawlable relation.
Clients MUST NOT assume that an OPDS Catalog Entry returned in the Acquisition Feed is a full representation of an OPDS Catalog Entry Resource, as described in the Section Partial and Complete Entries.
An OPDS Catalog provider MAY provide a single, consolidated Acquisition Feed that includes the complete representation of every unique OPDS Catalog Entry Document in an OPDS Catalog in an atom:feed to facilitate crawling and aggregation. Complete Acquisition Feeds SHOULD NOT be paginated unless they are extremely large.
This representation is called a Complete Acquisition Feed and each OPDS Catalog Entry MUST be ordered by atom:updated, with the most recently updated Atom Entries coming first in the document order.
If available, each OPDS Catalog Feed Document in the OPDS Catalog SHOULD contain an atom:link element with a relation of "http://opds-spec.org/crawlable" that references the Complete Acquisition Feed Resource.
A Complete Acquisition Feed MUST include a fh:complete element from [RFC5005] unless pagination is required. See Section 2 of [RFC5005] for the specification of the fh:complete element.
OPDS Catalog providers SHOULD use a compressed Content-Encoding when transmitting Complete Acquisition Feeds over HTTP. See Section 14.11 of [RFC2616] for more on compression.
OPDS Catalog providers MUST include Complete Catalog Entries when serializing a Complete Acquisition Feed.
OPDS Catalogs may be aggregated using the same techniques as Atom Feeds. Aggregators SHOULD use the atom:source element from Section 4.2.11 of [RFC4287] to include information about the original OPDS Catalog.
OPDS Catalogs may be referenced in HTML/XHTML pages, HTTP headers, or using other techniques. These links may reference both OPDS Catalog Entries or Feeds. Links to OPDS Catalog Entry Document Resources MUST use a type attribute of "application/atom+xml;type=entry;profile=opds-catalog". Links to OPDS Catalog Feed Document Resources MUST use a type attribute of "application/atom+xml;profile=opds-catalog".
The most common mechanism for encouraging the auto-discovery of OPDS Catalogs is to link from an HTML document to the OPDS Catalog Root Resource, using the auto-discovery pattern popularized by the syndicated feed community [AUTODISCOVERY].
Multiple links to OPDS Catalog Resources MAY be expressed in a single HTML document.
An example of two links inside an HTML page about the same Publication:
<link rel="related"
href="/opds-catalogs/root"
type="application/atom+xml;profile=opds-catalog"
title="Example OPDS Catalog" />
<link rel="alternate"
href="/entry/1"
type="application/atom+xml;type=entry;profile=opds-catalog"
title="Example OPDS Entry" />
Auto-discovery links MAY also be expressed using HTTP headers as defined in [DRAFT-Web-Linking].
OPDS Catalogs are delivered over HTTP. Authentication requirements for HTTP are covered in Section 11 of [RFC2616].
The type of authentication required for any OPDS Catalog is a decision to be made by the OPDS Catalog provider. OPDS Catalog clients are likely to face authentication schemes that vary across OPDS Catalogs. At a minimum, client and server implementations MUST be capable of being configured to use HTTP Basic Authentication [RFC2617] in conjunction with a connection made with TLS 1.0 [RFC2246] or a subsequent standards-track version of TLS supporting the conventions for using HTTP over TLS described in [RFC2818]. It is RECOMMENDED that OPDS Catalog clients be implemented in such a way that new authentication schemes can be deployed.
Because this protocol uses HTTP response status codes as the primary means of reporting the result of a request, OPDS Catalog providers are advised to respond to unauthorized or unauthenticated requests using an appropriate 4xx HTTP response code (e.g., 401 "Unauthorized" or 403 "Forbidden") in accordance with [RFC2617].
Many OPDS Catalog clients operate in mobile environments, which may impose strict limitations on bandwidth and processing resources. OPDS Catalog publishers are strongly encouraged to publish their OPDS Catalogs using compression and caching techniques and the partial feeds described in the Section Listing Acquisition Feeds. Implementers are encouraged to investigate and use alternative mechanisms regarded as equivalently good or better at the time of deployment. See [CACHING] for more on caching techniques.
OPDS Catalogs are Atom documents delivered over HTTP and thus subject to the security considerations found in Section 15 of [RFC2616] and Section 5 of [RFC4287].
OPDS Catalogs can contain XML External Entities as defined in Section 4.2.2 of [REC-xml]. OPDS Catalog implementations are not required to load external entities. External entities are subject to the same security concerns as any network operation and can alter the semantics of an OPDS Catalog Feed Document or OPDS Catalog Entry Document. The same issues exist for Resources linked to by elements such as atom:link and atom:content.
OPDS Catalog implementations handle URIs and IRIs. See Section 7 of [RFC3986] and Section 8 of [RFC3987] for security considerations related to their handling and use.
OPDS Catalogs can contain a broad range of content types including code that might be executable in some contexts. Malicious publishers could attempt to attack servers or other clients by injecting code into OPDS Catalog Feed Documents or OPDS Catalog Entry Documents or Media Resources.
Server implementations are strongly encouraged to verify that external content is safe prior to aggregating, processing, or publishing it. In the case of HTML, experience indicates that verification based on a white list of acceptable content is more effective than a black list of forbidden content.
Additional information about XHTML and HTML content safety can be found in Section 8.1 of [RFC4287].
The Atom Publishing Protocol [RFC5023] defines the Atom Format Type Parameter.
Publishers of OPDS Catalogs SHOULD use the "type" parameter to help clients distinguish between relations to OPDS Catalog Entries and OPDS Catalog Feeds.
Relations to OPDS Catalog Feed Document and OPDS Catalog Entry Document Resources SHOULD use a "profile" parameter following Section 4.3 of [RFC4288] with the value "opds-catalog". This profile parameter provides clients with an advisory hint that the Resource should be a component of an OPDS Catalog.
The complete media type for a relation to an OPDS Catalog Entry Document Resource SHOULD be:
application/atom+xml;type=entry;profile=opds-catalog
The complete media type for a relation to an OPDS Catalog Feed Document Resource SHOULD be:
application/atom+xml;profile=opds-catalog
The content and concepts within this specification are a product of the openpub community.
This appendix is informative.
The RELAX NG schema explicitly excludes elements in the OPDS Catalog namespace that are not defined in this revision of the specification. Requirements for Atom Protocol processors encountering such markup are given in Sections 6.2 and 6.3 of [RFC4287].
The Schema for OPDS Catalog Feed & Entry Documents:
# -*- rnc -*-
# RELAX NG Compact Syntax Grammar for OPDS Catalog Feed & Entry Documents
# Version 2010-08-18
namespace atom = "http://www.w3.org/2005/Atom"
namespace opds = "http://opds-spec.org/2010/catalog"
namespace local = ""
# The OPDS Catalog spec extends Atom (RFC4287), and the additions require some
# patterns not used in the Atom schema. The first is atomUriExceptOPDS, which
# is used to describe an atomLink whose rel value is an atomNCName (no-colon
# name) or any URI other than these from OPDS Catalogs. In these cases, no
# opds:price element should appear.
atomUriExceptOPDS = string - ( string "http://opds-spec.org/acquisition/buy"
| string "http://opds-spec.org/acquisition/borrow"
| string "http://opds-spec.org/acquisition/subscribe"
| string "http://opds-spec.org/acquisition/sample" )
# Next is OPDSUrisExceptBuy, which is used to describe an atomLink whose
# rel value is from OPDS Catalogs but is not ".../acquisition/buy". In such
# cases, an opds:price element is optional.
OPDSUrisExceptBuy = string "http://opds-spec.org/acquisition/borrow"
| string "http://opds-spec.org/acquisition/subscribe"
| string "http://opds-spec.org/acquisition/sample"
# To simplify OPDS Catalog validation, we do not use Schematron to assert that
# any atom:link with a rel value of ".../acquisition/buy" must be accompanied
# by one or more opds:price elements.
# Instead we rely on Relax NG to describe one of three situations:
# - the rel value is ".../acquisition/buy" and at least one opds:price element
# is required
# - the rel value is ".../acquisition/borrow" or ".../acquisition/subscribe" or
# ".../acquisition/sample", in case opds:price elements may be
# included; or
# - the value of the rel attribute is any other URI or an Atom-defined no-colon
# name, and no opds:price element is permitted
# Note that this OPDS Catalog schema includes atom.rnc, so that schema must be
# present for validation.
#
# Note also that atom.rnc defines atomUri as text and not as xsd:anyURI, and so
# wherever the Atom spec requires an IRI, the schema will not check the value
# against any URI pattern or logic. The OPDS Catalog schema overrides atom.rnc
# to provide a relatively accurate test. With the approval of XSD 1.1, the
# schema definition should change to xsd:anyURI to match what the spec text
# says.
include "atom.rnc" {
atomLink =
element atom:link {
atomCommonAttributes &
attribute href { atomUri } &
attribute type { atomMediaType }? &
attribute hreflang { atomLanguageTag }? &
attribute title { text }? &
attribute length { text }? &
((attribute rel { "http://opds-spec.org/acquisition/buy" }, opdsPrice+ )
|
(attribute rel { OPDSUrisExceptBuy }, opdsPrice*)
|
(attribute rel { atomNCName | ( atomUriExceptOPDS ) } ))? &
anyOPDSForeignElement* &
text
}
# Here is where OPDS Catalogs use John Cowan's pragmatic evaluation of an
# IRI. This modifies xsd:anyURI in XSD 1.0 to exclude ASCII characters not
# valid in 1.1 or IRI's without being escaped. This matches the OPDS and Atom
# specs, but not the non-normative atom.rnc.
atomUri = xsd:anyURI - xsd:string {pattern = '.*[ <>{}|^`"\\\n\r\t].*'}
# Here we override Atom to account for HTML abuse in the summary element,
# restricting it in OPDS Catalog to text:
atomSummary =
element atom:summary {
atomCommonAttributes,
attribute type { "text" }?,
text
}
}
anyOPDSForeignElement =
element * - ( atom:* | opds:* ) {
( attribute * { text }
| text
| anyElement )*
}
# An opds:price element should not contain a currency symbol; it is
# restricted to non-negative decimal numbers.
opdsPrice =
element opds:price {
atomCommonAttributes,
attribute currencycode { opdsPriceCurrencyCode },
xsd:decimal { minInclusive="0.0" }
}
# Instead of allowing every possible 3-letter or 3-digit combination as a
# currency code, here the permissible codes (as identified in ISO4217 as of
# 2010-08-25) are enumerated. In 2012 or so, that standard may add, remove or
# change some currency codes, thus requiring this schema to be updated. Note
# that codes for metals and funds are not included.
opdsPriceCurrencyCode = (
"AED" | "AFN" | "ALL" | "AMD" | "ANG" | "AOA" | "ARS" | "AUD" | "AWG" | "AZN" | "BAM" | "BBD" | "BDT" |
"BGN" | "BHD" | "BIF" | "BMD" | "BND" | "BOB" | "BOV" | "BRL" | "BSD" | "BTN" | "BWP" | "BYR" | "BZD" |
"CAD" | "CDF" | "CHE" | "CHF" | "CHW" | "CLF" | "CLP" | "CNY" | "COP" | "COU" | "CRC" | "CUC" | "CUP" |
"CVE" | "CZK" | "DJF" | "DKK" | "DOP" | "DZD" | "EEK" | "EGP" | "ERN" | "ETB" | "EUR" | "FJD" | "FKP" |
"GBP" | "GEL" | "GHS" | "GIP" | "GMD" | "GNF" | "GTQ" | "GYD" | "HKD" | "HNL" | "HRK" | "HTG" | "HUF" |
"IDR" | "ILS" | "INR" | "IQD" | "IRR" | "ISK" | "JMD" | "JOD" | "JPY" | "KES" | "KGS" | "KHR" | "KMF" |
"KPW" | "KRW" | "KWD" | "KYD" | "KZT" | "LAK" | "LBP" | "LKR" | "LRD" | "LSL" | "LTL" | "LVL" | "LYD" |
"MAD" | "MDL" | "MGA" | "MKD" | "MMK" | "MNT" | "MOP" | "MRO" | "MUR" | "MVR" | "MWK" | "MXN" | "MXV" |
"MYR" | "MZN" | "NAD" | "NGN" | "NIO" | "NOK" | "NPR" | "NZD" | "OMR" | "PAB" | "PEN" | "PGK" | "PHP" |
"PKR" | "PLN" | "PYG" | "QAR" | "RON" | "RSD" | "RUB" | "RWF" | "SAR" | "SBD" | "SCR" | "SDG" | "SEK" |
"SGD" | "SHP" | "SLL" | "SOS" | "SRD" | "STD" | "SVC" | "SYP" | "SZL" | "THB" | "TJS" | "TMT" | "TND" |
"TOP" | "TRY" | "TTD" | "TWD" | "TZS" | "UAH" | "UGX" | "USD" | "USN" | "USS" | "UYI" | "UYU" | "UZS" |
"VEF" | "VND" | "VUV" | "WST" | "XAF" | "XAG" | "XAU" | "XBA" | "XBB" | "XBC" | "XBD" | "XCD" | "XDR" |
"XFU" | "XOF" | "XPD" | "XPF" | "XPT" | "XTS" | "XXX" | "YER" | "ZAR" | "ZMK" | "ZWL" | "008" | "012" |
"032" | "036" | "044" | "048" | "050" | "051" | "052" | "060" | "064" | "068" | "072" | "084" | "090" |
"096" | "104" | "108" | "116" | "124" | "132" | "136" | "144" | "152" | "156" | "170" | "174" | "188" |
"191" | "192" | "203" | "208" | "214" | "222" | "230" | "232" | "233" | "238" | "242" | "262" | "270" |
"292" | "320" | "324" | "328" | "332" | "340" | "344" | "348" | "352" | "356" | "360" | "364" | "368" |
"376" | "388" | "392" | "398" | "400" | "404" | "408" | "410" | "414" | "417" | "418" | "422" | "426" |
"428" | "430" | "434" | "440" | "446" | "454" | "458" | "462" | "478" | "480" | "484" | "496" | "498" |
"504" | "512" | "516" | "524" | "532" | "533" | "548" | "554" | "558" | "566" | "578" | "586" | "590" |
"598" | "600" | "604" | "608" | "634" | "643" | "646" | "654" | "678" | "682" | "690" | "694" | "702" |
"704" | "706" | "710" | "748" | "752" | "756" | "760" | "764" | "776" | "780" | "784" | "788" | "800" |
"807" | "818" | "826" | "834" | "840" | "858" | "860" | "882" | "886" | "894" | "901" | "931" | "932" |
"934" | "936" | "937" | "938" | "940" | "941" | "943" | "944" | "946" | "947" | "948" | "949" | "950" |
"951" | "952" | "953" | "955" | "956" | "957" | "958" | "959" | "960" | "961" | "962" | "963" | "964" |
"968" | "969" | "970" | "971" | "972" | "973" | "974" | "975" | "976" | "977" | "978" | "979" | "980" |
"981" | "984" | "985" | "986" | "990" | "997" | "998" | "999"
)
This schema is also maintained in version control: http://openpub.googlecode.com/svn/trunk/schemas/opds_catalog.rnc