📖 Chapter 90: HTML for E-Books (EPUB 3)

The Package Document (package.opf)

The Publication Control Center: Dublin Core Metadata, Resource Manifests, Reading Spines, and Fallback Chains

LEARNING OBJECTIVES ⌵
  • Deconstruct the XML architecture of the EPUB 3 Package Document (package.opf).
  • Author mandatory Dublin Core metadata tags including dc:title, dc:creator, dc:identifier, and dcterms:modified.
  • Master the <manifest> element, media type declarations, and special item properties (nav, cover-image, scripted, mathml).
  • Construct the <spine> reading order, configure linear="no" auxiliary documents, and define media fallback chains.
🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation
🌐
1. Input
Directives & Tags
⚙️
2. Parse
Tokenizer & AST
🌳
3. Layout
Box Model & Flow
🎨
4. Render
GPU Paint & Composite
PHASE 1: INPUT & DIRECTIVES
Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine an international air cargo flight preparing for takeoff. Before the plane is cleared for departure, the aviation authorities require a master Flight Manifest. This document details every single cargo item on board (down to its exact weight and classification), lists every crew member and passenger, defines the exact sequential flight route from takeoff to landing, and outlines contingency plans if an alternate airport is needed.

If a stray package is found inside the cargo hold that is not recorded in the manifest, or if an item listed in the manifest is missing from the plane, the flight is immediately grounded.

+-------------------------------------------------------------------------+
|                       THE PACKAGE DOCUMENT (package.opf)                 |
|                                                                         |
|  1. <metadata>   -> Book title, Author, ISBN, Modification Timestamp   |
|  2. <manifest>   -> Exhaustive inventory of EVERY file in the archive  |
|  3. <spine>      -> The strict sequential page-turn reading order      |
|  4. <guide>      -> (Legacy EPUB 2) Cover and TOC reference pointers   |
+-------------------------------------------------------------------------+

The Package Document (conventionally named package.opf or content.opf) is the supreme brain of an EPUB 3 e-book. An e-reader does not crawl directories to discover files; if a stylesheet, font, or image exists in the folder but is omitted from the <manifest>, the reading system acts as though it does not exist and validators will reject the book outright.

Technical Deep Dive & Specifications

The Anatomy of package.opf

The Package Document is written in XML using the root <package> element. It is composed of three mandatory sections and one optional legacy section:

                  +-----------------------------------+
                  |      <package version="3.0">      |
                  +-----------------------------------+
                                    |
        +---------------------------+---------------------------+
        |                           |                           |
        v                           v                           v
+---------------+           +---------------+           +---------------+
|  <metadata>   |           |  <manifest>   |           |    <spine>    |
| (Dublin Core) |           |  (All Assets) |           | (Reading Flow)|
+---------------+           +---------------+           +---------------+

1. The <package> Root Element

<package xmlns="http://www.idpf.org/2007/opf" 
         unique-identifier="pub-id" 
         version="3.0" 
         prefix="rendition: http://www.idpf.org/vocab/rendition/#">
  • unique-identifier: References the id of the dc:identifier element that uniquely distinguishes this book (e.g., an ISBN or UUID).
  • version: Must be "3.0".

2. The <metadata> Section

Mandatory elements governed by the Dublin Core Metadata Initiative (xmlns:dc="http://purl.org/dc/elements/1.1/"):

  • <dc:identifier id="pub-id">: Unique identifier (URN, ISBN, UUID).
  • <dc:title>: Title of the publication.
  • <dc:language>: RFC 5646 language tag (e.g., en, es-MX, ja).
  • <meta property="dcterms:modified">: Mandatory in EPUB 3. An ISO-8601 UTC timestamp representing the last modification time (YYYY-MM-DDTHH:MM:SSZ).

3. The <manifest> Section

Every single file inside the EPUB payload must have an entry:

<item id="ch01" href="text/ch01.xhtml" media-type="application/xhtml+xml" />
  • id: Unique XML ID used to reference this item in the spine or fallback chains.
  • href: URI path relative to the package.opf file location.
  • media-type: Exact standard MIME type.
  • properties: Special keywords indicating specialized content:
    • nav: Identifies the EPUB 3 Navigation Document (nav.xhtml). Exactly one item must have this.
    • cover-image: Identifies the primary cover artwork.
    • scripted: Declares that the XHTML document contains JavaScript.
    • mathml: Declares that the document contains MathML formulas.
    • svg: Declares that the document contains inline SVG.
    • remote-resources: Declares audio/video loaded from external HTTPS URLs.

EPUB 3 Core Media Types Table

Content Type Official MIME Type
XHTML Content Document application/xhtml+xml
EPUB 3 Navigation Document application/xhtml+xml (with properties="nav")
CSS Stylesheets text/css
Images (PNG / JPEG / GIF / SVG / WebP) image/png, image/jpeg, image/gif, image/svg+xml, image/webp
Fonts (WOFF / WOFF2 / OTF / TTF) font/woff, font/woff2, application/font-sfnt or font/otf, font/ttf
Audio (MP3 / AAC) audio/mpeg, audio/mp4
Video (H.264 MP4 / WebM) video/mp4, video/webm
Legacy NCX Navigation application/x-dtbncx+xml

4. The <spine> Section

Defines the linear sequence in which content documents are displayed when a user flips pages forward:

<spine toc="ncx">
  <itemref idref="cover" linear="no" />
  <itemref idref="nav" />
  <itemref idref="ch01" />
  <itemref idref="ch02" />
  <itemref idref="answers" linear="no" />
</spine>
  • idref: Matches the id of an item declared in the <manifest>.
  • linear="yes" (default): Primary narrative flow.
  • linear="no": Auxiliary content (e.g., answer keys, pop-up definitions, full-screen image zooms) that should not appear during sequential reading, but can be reached via explicit hyperlinks.

💻 Interactive Code Playground

Starter Code: Complete Production package.opf

Line-by-Line Code Breakdown

  • Line 2–5 (<package ...>): Sets up the root package container with version="3.0" and links unique-identifier="book-id".
  • Line 8–17 (<metadata>): Declares standard Dublin Core bibliographic data.
    • Line 9: urn:uuid:... matches the root unique-identifier.
    • Line 15: dcterms:modified formatted in exact ISO-8601 UTC timestamp format.
  • Line 21 (properties="nav"): Crucial flag informing the e-reader that text/nav.xhtml is the official navigation hierarchy.
  • Line 22 (toc.ncx): Preserves compatibility with legacy EPUB 2 hardware devices.
  • Line 26 (properties="mathml"): Signals to the reading system that ch01.xhtml requires the MathML rendering pipeline.
  • Line 35 (properties="cover-image"): Designates images/cover.jpg as the book's shelf thumbnail in e-book library apps.
  • Line 43 (<spine toc="ncx">): Sets up the linear reading chain and binds the legacy NCX table of contents.
  • Line 44 (linear="no"): Ensures the cover page does not interrupt the narrative if the user presses "Previous Page" from Chapter 1.

Expected Validator (epubcheck) Output

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf" 
         unique-identifier="book-id" 
         version="3.0" 
         prefix="rendition: http://www.idpf.org/vocab/rendition/#">

  <!-- ================= 1. METADATA ================= -->
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:identifier id="book-id">urn:uuid:9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d</dc:identifier>
    <dc:title>Architecting Resilient Distributed Systems</dc:title>
    <dc:creator id="author">Dr. Elena Rostova</dc:creator>
    <meta refines="#author" property="role" scheme="marc:relators">aut</meta>
    <dc:publisher>Apex Technical Press</dc:publisher>
    <dc:language>en-US</dc:language>
    <dc:date>2026-08-20</dc:date>
    <meta property="dcterms:modified">2026-08-20T14:30:00Z</meta>
    <meta name="cover" content="cover-img" />
  </metadata>

  <!-- ================= 2. MANIFEST ================= -->
  <manifest>
    <!-- Navigation Documents -->
    <item id="nav" href="text/nav.xhtml" media-type="application/xhtml+xml" properties="nav" />
    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" />

    <!-- Content Documents -->
    <item id="cover-page" href="text/cover.xhtml" media-type="application/xhtml+xml" />
    <item id="ch01" href="text/ch01.xhtml" media-type="application/xhtml+xml" properties="mathml" />
    <item id="ch02" href="text/ch02.xhtml" media-type="application/xhtml+xml" properties="svg" />
    <item id="appendix" href="text/appendix.xhtml" media-type="application/xhtml+xml" />

    <!-- Stylesheets -->
    <item id="css-core" href="styles/core.css" media-type="text/css" />
    <item id="css-typography" href="styles/typography.css" media-type="text/css" />

    <!-- Images -->
    <item id="cover-img" href="images/cover.jpg" media-type="image/jpeg" properties="cover-image" />
    <item id="fig-consensus" href="images/consensus.svg" media-type="image/svg+xml" />

    <!-- Embedded Fonts -->
    <item id="font-fira-regular" href="fonts/FiraCode-Regular.woff2" media-type="font/woff2" />
    <item id="font-fira-bold" href="fonts/FiraCode-Bold.woff2" media-type="font/woff2" />
  </manifest>

  <!-- ================= 3. SPINE ================= -->
  <spine toc="ncx">
    <itemref idref="cover-page" linear="no" />
    <itemref idref="nav" />
    <itemref idref="ch01" />
    <itemref idref="ch02" />
    <itemref idref="appendix" linear="yes" />
  </spine>

</package>
Validating against EPUB version 3.3 ...
Validating package manifest references... [OK]
Checking Dublin Core metadata integrity... [OK]
Checking dcterms:modified timestamp format... [OK]
Checking nav property declaration... [OK]
Spine reading order resolved: 5 documents.
EpubCheck completed with 0 errors, 0 warnings.

🏋️ Hands-On Exercise

🎯 The Challenge: Author an OPF Manifest with Fallback Chain

Instructions:

  1. Author a valid <manifest> and <spine> snippet for an e-book with a non-standard vector format (diagram.ai - Adobe Illustrator) that falls back to a standardized PNG (diagram.png).
  2. Add a scripted interactive simulation document simulation.xhtml with the scripted property.
  3. Make simulation.xhtml a non-linear spine item (linear="no").

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

  1. Orphaned (Unmanifested) Files in the Archive: If you drop an unused image photo.jpg into your images folder but do not declare it in <manifest>, epubcheck will reject the publication with a fatal Resource not declared in manifest error. Every single file in the payload must be declared.
  2. Malformed dcterms:modified Timestamp: Writing 2026-08-20 or including milliseconds 2026-08-20T14:30:00.123Z will fail strict OPF schemas. The format must strictly be YYYY-MM-DDTHH:MM:SSZ.
  3. Missing properties="nav": Failing to place properties="nav" on the navigation document entry. An e-reader relies on this exact property tag to discover its Table of Contents.

💡 Pro Tips

  1. Automate Manifest Generation: Never hand-craft OPF manifests for large books. Write a Node.js or Python build script that traverses your content directory, calculates correct MIME types, and outputs the <manifest> XML automatically.
  2. Use RFC 4122 Version 4 UUIDs for Identifiers: If your book lacks a formal commercial ISBN, generate a random UUID (urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6) to guarantee global uniqueness across reading system databases.

📌 Key Takeaways

  • The package.opf file is the authoritative registry defining metadata, assets, reading order, and fallbacks.
  • The <metadata> block must contain dc:identifier, dc:title, dc:language, and an ISO-8601 UTC dcterms:modified timestamp.
  • Every resource inside the EPUB payload must be registered in <manifest> with its exact MIME type.
  • The properties attribute marks special items such as nav, cover-image, scripted, and mathml.
  • The <spine> defines the sequential reading order, using linear="no" for auxiliary, non-narrative content.
  • --
⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE
3x
STREAK!
BONUS ACTIVE
COMBO
? Question 1 / 3

What happens if an image diagram.png is placed inside the EPUB ZIP archive but is NOT declared in the package.opf <manifest>?

Question 1 / 3 Topic: HTML Fundamentals
00:45 REMAINING
XP REWARD
+250 XP
3x
STREAK!
BONUS ACTIVE
COMBO
? Question 2 / 3

Which attribute and value must be attached to the <item> tag representing nav.xhtml in the <manifest>?

Question 2 / 3 Topic: HTML Fundamentals
00:45 REMAINING
XP REWARD
+250 XP
3x
STREAK!
BONUS ACTIVE
COMBO
? Question 3 / 3

What is the function of linear="no" on an <itemref> element inside the <spine>?

Question 3 / 3 Topic: HTML Fundamentals
00:45 REMAINING
XP REWARD
+250 XP