#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:
-
Metadata about the publication as a whole.
-
Links to related resources, including one mandatory link ("self") to the canonical location of the manifest.
-
A spine that enumerates the components of the publication, their ordering, and their properties.
-
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:
Role | Semantics | Compact? | Required? |
---|---|---|---|
spine | Identifies a list of resources in reading order for the publication. | Yes | Yes |
resources | Identifies resources that are necessary for rendering the publication. | Yes | No |
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
:
Name | Value | Format | Required? |
---|---|---|---|
href | link location | URI | Yes |
type | MIME type of resource | MIME media type | Yes |
title | title of the linked resource | text | No |
rel | relationship | list of rel values or URI for an extension | No |
properties | properties associated with the linked resource | list of property values | No |
height | indicates the height of the linked resource in pixels | integer where the value is greater than zero | No |
width | indicates the width of the linked resource in pixels | integer where the value is greater than zero | No |
duration | indicates the length of the linked resource in seconds | ISO 8601 duration | No |
templated | indicates linked resource is a URI template | boolean, defaults to false | No |
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:
Name | URI | Description | Required? |
---|---|---|---|
Default Context | http://idpf.org/epub.jsonld | Default context definition used in every Web Publication Manifest. | Yes |
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="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="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.