OPF XML: Declaring the Manifest and Spine

The Open Packaging Format (OPF) file, typically named content.opf or package.opf, serves as the central directory for an EPUB digital book. Within its root <package> element, the document relies on two critical child elements—the <manifest> and the <spine>—to organize the publication. While the manifest provides a comprehensive inventory of all resource files included in the digital book, the spine defines the precise linear reading order of those resources.

Declaring the Manifest

The <manifest> element acts as a complete registry of every file contained within the EPUB container, including XHTML documents, stylesheets, images, fonts, audio files, and embedded scripts. Reading systems reject or fail to render files that are present in the package directory but omitted from the manifest.

Every resource inside the <manifest> is defined using an individual <item> element with specific required and optional attributes:

• id (Required): A unique XML identifier assigned to the resource. This ID is referenced by other parts of the OPF, specifically the spine.
• href (Required): The relative URI path pointing to the physical file location within the EPUB archive.
• media-type (Required): The standard MIME type representing the file format (e.g., application/xhtml+xml for content files, text/css for stylesheets, image/jpeg for images).
• properties (Optional): Special keywords indicating unique roles, such as nav for the EPUB 3 navigation document, cover-image for the primary cover graphic, or scripted for interactive pages.

<manifest>
  <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>
  <item id="style" href="styles/main.css" media-type="text/css"/>
  <item id="cover" href="images/cover.jpg" media-type="image/jpeg" properties="cover-image"/>
  <item id="chapter1" href="text/chapter01.xhtml" media-type="application/xhtml+xml"/>
  <item id="chapter2" href="text/chapter02.xhtml" media-type="application/xhtml+xml"/>
</manifest>

Declaring the Spine

The <spine> element determines the reading sequence of the publication. While the manifest lists resources in any order, the spine arranges content documents into the exact chronological order presented to the reader as they turn pages.

Only top-level document resources (primarily XHTML files) are included in the spine; assets like CSS, images, and fonts are excluded. The spine contains a series of <itemref> elements that reference items previously declared in the manifest:

• idref (Required): Matches the exact id attribute of an item declared in the <manifest>.
• linear (Optional): Specifies whether the document is part of the primary reading flow (yes, the default) or supplementary material like pop-ups or notes (no).
• id (Optional): A unique identifier for the specific <itemref> element itself.

The <spine> element can also include the page-progression-direction attribute (set to ltr for left-to-right languages or rtl for right-to-left languages like Arabic or Japanese) to control navigation direction.

<spine page-progression-direction="ltr">
  <itemref idref="cover" linear="no"/>
  <itemref idref="nav"/>
  <itemref idref="chapter1"/>
  <itemref idref="chapter2"/>
</spine>

How the Manifest and Spine Work Together

When an e-reader opens an EPUB file, it reads the <spine> from top to bottom. For each <itemref>, the reading engine matches the idref to the corresponding id in the <manifest>. Through this lookup, the parser resolves the href to locate the source file and uses the media-type to determine how to parse and render the content on screen.