drafts

OPDS Logo

OPDS Catalog 2.0

Open Publication Distribution System (OPDS) 2.0 is based on the Readium Web Publication Manifest model and JSON-LD, with a focus on aggregating publications together in order to facilitate their distribution.

This version:

Previous version:

Editors:

Participate:

Status of this Document

This document is a draft of the 2.0 version of the OPDS Catalog specification.

Table of Contents

Overview

OPDS 2.0 is based on the same abstract model as the Readium Web Publication Manifest.

Compared to previous versions of the OPDS specification:

In the Readium Web Publication Manifest model, everything has to be a collection:

An OPDS 2.0 Catalog Feed is a collection too, with the following requirements:

OPDS 2.0 feeds are identified using the following media type: application/opds+json

1. Collections

OPDS 2.0 introduces five new collection roles to the Readium Web Publication Manifest model.

Role Semantics Compact? Required? Reference
navigation An ordered list of links meant to browse a catalog in depth. Yes No OPDS 2.0
publications Contains a list of publications. No No OPDS 2.0
images Visual representations for a publication. Yes No OPDS 2.0
facets Links meant to obtain a sub-set of the current list of publications, or the same list in a different order. No No OPDS 2.0
groups Structural element in a catalog meant to contain navigation or publications collections. No No OPDS 2.0

1.1. Navigation

A navigation collection is meant to provide links that an end user can follow in order to browse a catalog.

Each Link Object must contain a title.

While a navigation link may point to any number of format, it is recommended to either link to other OPDS 2.0 feeds (application/opds+json) or to HTML (text/html).

Catalog providers should also attempt to provide a meaningful link relation for each Link Object in a navigation collection.

Example

{
  "metadata": {
    "title": "Example for navigation"
  },
  
  "links": [
    {"rel": "self", "href": "http://example.com/opds", "type": "application/opds+json"}
  ],
  
  "navigation": [
    {
      "href": "/new", 
      "title": "New Publications", 
      "type": "application/opds+json", 
      "rel": "current"
    },
    {
      "href": "/popular", 
      "title": "Popular Publications", 
      "type": "application/opds+json", 
      "rel": "http://opds-spec.org/sort/popular"
    }
  ]
}

1.2. Publications

A publications collection is meant to list publications in an OPDS feed.

Publications can either be:

All publications listed in such a collection must provide a self link that will be used by OPDS clients to identify, reference and access publications.

Example

{
  "metadata": {
    "title": "Example listing publications"
  },
  
  "links": [
    {"rel": "self", "href": "http://example.com/new", "type": "application/opds+json"}
  ],
  
  "publications": [
    {
      "metadata": {
        "@type": "http://schema.org/Book",
        "title": "Moby-Dick",
        "author": "Herman Melville",
        "identifier": "urn:isbn:978031600000X",
        "language": "en",
        "modified": "2015-09-29T17:00:00Z"
      },
      "links": [
        {"rel": "self", "href": "http://example.org/manifest.json", "type": "application/webpub+json"}
      ],
      "images": [
        {"href": "http://example.org/cover.jpg", "type": "image/jpeg", "height": 1400, "width": 800},
        {"href": "http://example.org/cover-small.jpg", "type": "image/jpeg", "height": 700, "width": 400},
        {"href": "http://example.org/cover.svg", "type": "image/svg+xml"}
      ]
    }
  ]
}

1.3. Images

While previous versions of OPDS relied on link relations to identify visual representations, OPDS 2.0 introduces a dedicated collection role for that purpose.

This new collection role is mostly meant to support responsive images across all types of devices.

Link Objects in images may include any number of image format, resolution or aspect ratio.

At least one image resource must use one of the following formats: image/jpeg, image/png or image/gif.

Each publication listed in an OPDS feed must contain an images collection.

Example

"images": [
  {
    "href": "http://example.org/cover.jpg", 
    "type": "image/jpeg", 
    "height": 1400, 
    "width": 800
  },
  {
    "href": "http://example.org/cover-small.jpg", 
    "type": "image/jpeg", 
    "height": 700, 
    "width": 400
  },
  {
    "href": "http://example.org/cover.svg", 
    "type": "image/svg+xml"
  }
]

1.4. Facets

Facets are meant to allow a user to explore a large collection of publications by either changing the order or obtaining a sub-set for the current feed.

The facets role is meant to indicate that a collection contains a facet group. Each facet group:

Example

{
  "metadata": {
    "title": "Example for facets"
  },
  
  "links": [
    {"rel": "self", "href": "http://example.com/faceted", "type": "application/opds+json"}
  ],
  
  "facets": [
    {
      "metadata": {
        "title": "Language"
      },
      "links": [
        {"href": "/fr", "type": "application/opds+json", "title": "French", "properties": {"numberOfItems": 10}},
        {"href": "/en", "type": "application/opds+json", "title": "English", "properties": {"numberOfItems": 40}},
        {"href": "/de", "type": "application/opds+json", "title": "German", "properties": {"numberOfItems": 6}}
      ]
    }
  ]
}

1.5. Groups

When an OPDS catalog feed needs to contain more than one navigation or publications collection, it needs to rely on the groups role.

Groups are meant to contain:

Each group must provide a title in its metadata.

In addition, each group may also provide:

Example 1: Repeating navigation using groups

{
  "metadata": {
    "title": "Example for groups"
  },
  
  "links": [
    {"rel": "self", "href": "http://example.com/grouped", "type": "application/opds+json"}
  ],
  
  "groups": [
    {
      "metadata": {"title": "Main Menu"},
      "navigation": [
        {"href": "/new", "title": "New Publications", "type": "application/opds+json", "rel": "http://opds-spec.org/sort/new"},
        {"href": "/popular", "title": "Popular Publications", "type": "application/opds+json", "rel": "http://opds-spec.org/sort/popular"}
      ]
    },
    {
      "metadata": {"title": "Formats"},
      "navigation": [
        {"href": "/ebooks", "title": "EBooks", "type": "application/opds+json", "rel": "subsection"},
        {"href": "/audiobooks", "title": "Audiobooks", "type": "application/opds+json", "rel": "subsection"}
      ]
    }
  ]
}

Example 2: Mixing navigation & publications

A group may for example contain a publications collection with 5 publications embedded, but indicate in numberOfItems that there are 50 publications in total and provide a link to that full collection.

{
  "metadata": {
    "title": "Example for groups"
  },
  
  "links": [
    {"rel": "self", "href": "http://example.com/grouped", "type": "application/opds+json"}
  ],
  
  "groups": [
    {
      "metadata": {"title": "Main Menu"},
      "navigation": [
        {"href": "/new", "title": "New Publications", "type": "application/opds+json", "rel": "http://opds-spec.org/sort/new"},
        {"href": "/popular", "title": "Popular Publications", "type": "application/opds+json", "rel": "http://opds-spec.org/sort/popular"}
      ]
    },
    {
      "metadata": {
        "title": "Featured Books",
        "numberOfItems": 20
      },
      "links": [
        {"rel": "self", "href": "/featured", "type": "application/opds+json"}
      ],
      "publications": [
        {
          "metadata": {
            "@type": "http://schema.org/Book",
            "title": "Moby-Dick",
            "author": "Herman Melville",
            "identifier": "urn:isbn:978031600000X",
            "language": "en",
            "modified": "2015-09-29T17:00:00Z"
          },
          "links": [
            {"rel": "self", "href": "http://example.org/manifest.json", "type": "application/webpub+json"}
          ],
          "images": [
            {"href": "http://example.org/cover.jpg", "type": "image/jpeg", "height": 1400, "width": 800},
            {"href": "http://example.org/cover-small.jpg", "type": "image/jpeg", "height": 700, "width": 400},
            {"href": "http://example.org/cover.svg", "type": "image/svg+xml"}
          ]
        }
      ]
    }
  ]
}

Each catalog may provide the ability to search.

A catalog can indicate that search is available by providing a Link Object in links where the relation is set to “search”:

{
  "rel": "search",
  "href": "search{?query}", 
  "type": "application/opds+json", 
  "templated": true
}

Search is always expressed using a URI template with at least one query parameter: “query”. This query parameter enables basic keyword search.

In addition to basic keyword search, an OPDS catalog may allow advanced search on any metadata element defined in the Default Context Document.

For example the following Link Object allows keyword search as well as restricting search on the “title” or “author” of a publication:

{
  "rel": "search",
  "href": "search{?query,title,author}", 
  "type": "application/opds+json", 
  "templated": true
}

3. Pagination

An OPDS Catalog can contain a very large number of publications. While such catalogs are usually broken down using navigation, facets and groups, a single sub-collection could still contain thousands of publications.

To handle that issue, OPDS 2.0 supports pagination based on metadata and links.

In metadata a feed can contain the following elements:

Key Definition Format
numberOfItems Indicates the total number of items in a collection. Integer
itemsPerPage Indicates the number of items displayed per page for the current collection. Integer
currentPage Indicates the current page number. Integer

In links the following relations can be used:

Relation Definition Reference
next Refers to the next resource in a ordered series of resources. HTML4
previous Refers to the previous resource in an ordered series of resources. Synonym for “prev”. HTML4
first An IRI that refers to the furthest preceding resource in a series of resources. RFC5988
last An IRI that refers to the furthest following resource in a series of resources. RFC5988

Example: Basic pagination

{
  "metadata": {
    "title": "Paginated feed",
    "numberOfItems": 5678,
    "itemsPerPage": 50,
    "currentPage": 2
  },
  "links": [
    {"rel": "self", "href": "/?page=2", "type": "application/opds+json"},
    {"rel": ["first", "previous"], "href": "/?page=1", "type": "application/opds+json"},
    {"rel": "next", "href": "/?page=3", "type": "application/opds+json"},
    {"rel": "last", "href": "/?page=114", "type": "application/opds+json"}
  ]
}

4. Publications

4.1. OPDS Publication

An OPDS Publication is essentially a Readium Web Publication without the requirement to include a spine collection:

4.2. Metadata

Metadata expression in OPDS 2.0 is based on the Readium Web Publication Manifest model and its default context.

OPDS 2.0 introduces a slight extension to this model by allowing optional links at a metadata level in the following elements:

The links element is used for that purpose with an array of Link Objects.

Example: Publication metadata enhanced with links

"metadata": {
  "@type": "http://schema.org/EBook",
  "identifier": "urn:isbn:9780000000002",
  "title": "A Journey into the Center of the Earth",
  "author": {
    "name": "Jules Verne",
    "identifier": "http://isni.org/isni/0000000121400562",
    "sortAs": "Verne, Jules",
    "links": [
      {"href": "/author/0000000121400562", "type": "application/opds+json"}
    ]
  },
  "translator": "Frederick Amadeus Malleson",
  "language": "en",
  "publisher": "SciFi Publishing Inc.",
  "modified": "2016-02-22T11:31:38Z",
  "description": "The story involves German professor Otto Lidenbrock who believes there are volcanic tubes going toward the centre of the Earth. He, his nephew Axel, and their guide Hans descend into the Icelandic volcano Snæfellsjökull, encountering many adventures, including prehistoric animals and natural hazards, before eventually coming to the surface again in southern Italy, at the Stromboli volcano.",
  "belongsTo": {
    "series": {
      "name": "The Extraordinary Voyages",
      "position": 3,
      "links": [
        {"href": "/series/167", "type": "application/opds+json"}
      ]
    },
    "collection": "SciFi Classics"
  }
}

In OPDS 2.0, the concept of an Acquision Link is not as central as in OPDS 1.x since publications can also be accessed through a manifest.

That said, for publications that are strictly accessible through a download or require specific interactions, the concept remains.

OPDS 2.0 allows the following relations to indicate that a publication can be acquired:

Relation Definition Reference
http://opds-spec.org/acquisition Fallback acquisition relation when no other relation is a good fit to express the nature of the transaction. OPDS 1.2
http://opds-spec.org/acquisition/open-access Indicates that a publication is freely accessible without any requirement, including authentication. OPDS 1.2
http://opds-spec.org/acquisition/borrow Indicates that a publication can be borrowed for a limited period of time. OPDS 1.2
http://opds-spec.org/acquisition/buy Indicates that a publication can be purchased for a given price. OPDS 1.2
http://opds-spec.org/acquisition/sample Indicates that a sub-set of the full publication is freely accessible at a given URI, without any prior requirement. OPDS 1.2
preview Indicates that a sub-set of the full publication is freely accessible at a given URI, without any prior requirement. RFC6903
http://opds-spec.org/acquisition/subscribe Indicates that a publication be subscribed to, usually as part of a purchase and for a limited period of time. OPDS 1.2

An OPDS 2.0 catalog should not use “http://opds-spec.org/acquisition” when another link relation is suitable to express the interaction.

In addition to link relations, OPDS 2.0 also defines a number of properties to express relevant information for these interactions:

Key Definition Format
price Provides the acquisition price in a given currency. Price Object
indirectAcquisition Provides the expected download format for a publication, after an acquisition through an intermediate resource. Array of Acquisition Objects

The Price Object can contain the following keys:

Key Definition Format
currency Provides the currency for a specific price. ISO 4217 currency code
value Provides the decimal value for a specific price. Float

The Acquisition Object can contain the following keys:

Key Definition Format
type Indicates the media type in which the publication can be indirectly acquired. MIME Media Type
child Contains an additional level of indirection if necessary. Array of Acquisition Objects

Example 1: Simple paid acquisition

{
  "href": "/buy",
  "rel": "http://opds-spec.org/acquisition/buy",
  "type": "application/epub+zip",
  "properties": {
    "price": {
      "currency": "USD",
      "value": 4.99
    }
  }
}

Example 2: Indirect Acquisition through an HTML document

{
  "href": "/buy",
  "rel": "http://opds-spec.org/acquisition/buy",
  "type": "text/html",
  "properties": {
    "price": {
      "currency": "USD",
      "value": 4.99
    },
    "indirectAcquisition": [{"type": "application/epub+zip"}]
  }
}

Appendix A. JSON Schema

A JSON Schema for OPDS 2.0 is available under version control at https://github.com/opds-community/drafts/tree/master/schema

For the purpose of validating an OPDS 2.0 catalog, use the following JSON Schema resources: