Web Publication Manifest

Example

{
  "metadata": {
    "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/epub+json"},
    {"rel": "alternate", "href": "http://example.org/publication.epub", "type": "application/epub+zip"},
    {"rel": "search", "href": "http://example.org/?q={searchTerms}", "type": "text/html", "templated": true}
  ],

  "spine": [
    {"href": "c001.html", "type": "text/html", "title": "Chapter 1"}, 
    {"href": "c002.html", "type": "text/html", "title": "Chapter 2"}
  ],

  "resources": [
    {"href": "cover.jpg", "type": "image/jpeg", "height": 600, "width": 400, "rel": "cover"},
    {"href": "style.css", "type": "text/css"}, 
    {"href": "whale.jpg", "type": "image/jpeg"}, 
    {"href": "boat.svg", "type": "image/svg+xml"}, 
    {"href": "notes.html", "type": "text/html"}
  ]
}

Introduction

EPUB exists because the web doesn't allow us to easily speak about collections of documents. Web documents can link to each other, and link relations let you say a few things about what's on the other end of a link. But you can't say two documents are part of a larger entity. You can't say this metadata applies to a group of documents.

EPUB has filled that gap with the package file, which includes publication metadata, a list of files that make up the publication ("manifest"), and information about their ordering ("spine"). However, there's a lot of duplication and indirection involved in the XML, and we believe a simpler conceptual model is possible.

We can describe everything we need to know about the bundle of documents that forms a publication with a relatively simple JSON structure. It consists of:

1. Metadata about the publication as a whole.

2. Links to related resources, including one mandatory link ("self") to the canonical location of the manifest.

3. A spine that enumerates the components of the publication, their ordering, and their properties.

4. Additional resources that are not part of the spine but used by the publication (CSS, images, fonts).

The JSON Manifest Document

Data Model

The manifest itself is a collection. EPUB 3.0.1 defines a collection as "a related group of resources."

A collection consists of metadata, links, and subcollections. The key for a collection is the role of that collection:

role
  metadata
  links
  [subcollections]

A manifest must have one spine collection where the components of the publications are listed in the linear reading order. Other resources are listed in a resources collection.

Collections that do not contain any metadata or subcollections (also called "compact collections"), can use a more compact syntax where they simply contain an array of Link Objects.

Collection Roles

This specification defines two collection roles that are the building blocks of any manifest:

Additional collection roles are defined in the EPUB Collection Roles Registry.

Extensions to these collection roles must use a URI as their JSON key.

Links

A manifest must contain at least one link using the self relationship. This link must point to the canonical location of the manifest using an absolute URI:

"links": [{
  "rel": "self",
  "href": "http://example.org/manifest.json",
  "type": "application/epub+json"}
]

A manifest may also contain other links, such as a alternate link to an EPUB 3.1 version of the publication for example.

The Link Object

The Link Object is used in links and in compact collections to list resources associated to a collection. It requires at least the presence of href and type:

Metadata

JSON-LD provides an easy and standard way to extend existing JSON document: through the addition of a context, we can associate keys in a document to Linked Data elements from various vocabularies.

The Web Publication Manifest relies on JSON-LD to provide a context for the metadata object of the manifest.

While JSON-LD is very flexible and allows the context to be defined in-line (local context) or referenced (URI), the Web Publication Manifest restricts context definition strictly to references.

The Web Publication Manifest defines an initial registry of well-known context documents, which currently includes the following references:

The full up-to-date registry is available directly on Github.

Content Documents

Web Publication Manifest content documents follow the usual rules of EPUB 3.1, but also allows HTML in addition to XHTML.

Discovering a Manifest

To indicate that a content document is associated with a particular Web Publication Manifest, use a link element in the HTML head:

<link href="https://github.com/dauwhe/epub31-bff/blob/master/manifest.json" rel="manifest" type="application/epub+json">

The manifest can also be associated with any resources served over HTTP using the Link header:

Link: <http://example.org/manifest.json>; rel="manifest";
         type="application/epub+json"

Table of Contents

A Web Publication Manifest can indicate that a table of contents is available using the contents rel value in a Link Object listed in spine or resources:

{"rel": "contents", "href": "contents.html", "type": "text/html"}

The link must point to an HTML or XHTML document and may be a Navigation Document as defined in EPUB 3.1.

A Web Publication Manifest client may also rely on the title key included in each Link Object of the spine to extract a minimal table of contents.

Cover

A Web Publication Manifest can also provide a cover using the cover rel value in a Link Object listed in spine, resources or links:

{"rel": "cover", "href": "cover.jpg", "type": "image/jpeg", "height": 600, "width": 400}

The link must point to an image using one of the following media types: image/jpeg, image/png, image/gif or image/svg+xml.

Containers

Classic EPUBs must be packaged in an EPUB Container as defined in the OCF specification.

The Web Publication Manifest is primarily meant to be distributed unpackaged and exploded on the Web.

That said, a Web Publication Manifest may be included in a classic EPUB but reading systems have no obligation to access the manifest.

If a Web Publication Manifest is included in an EPUB container, the following restrictions apply:

• the manifest document must be named manifest.json and must appear at the top level of the container
• the OPF of the primary rendition must include a link to the manifest where the relationship is set to alternate

<link rel="alternate" href="https://github.com/dauwhe/epub31-bff/blob/master/manifest.json" media-type="application/epub+json" />

Live Demo

A live demo of a Web Publication is available at: https://dauwhe.github.io/epub31-bff/examples/MobyDick/

The manifest for this demo is available at: https://dauwhe.github.io/epub31-bff/examples/MobyDick/manifest.json

In addition to a Web Publication Manifest, this live demo also uses a Service Worker to provide offline reading and a Web App Manifest.

Acknowledgements

All the JSON serialization work is based on ideas from Hadrien Gardeur.