Skip to content

Latest commit

 

History

History
210 lines (140 loc) · 8.67 KB

README.md

File metadata and controls

210 lines (140 loc) · 8.67 KB
Raw

#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:

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.