EPUB 3 Format Guide: Deep Dive into content.opf

 Hand editing epub files now so I can distribute the story I just wrote.

Overview

EPUB 3 is the latest major version of the EPUB specification (currently EPUB 3.3 as of 2023). The content.opf file (also called the Package Document) is the heart of every EPUB—it describes the publication's metadata, lists all content files, and defines the reading order.

File Structure

The OPF file is an XML document with this basic structure:

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="uid">
  <metadata>...</metadata>
  <manifest>...</manifest>
  <spine>...</spine>
  <guide>...</guide> <!-- Optional, deprecated in EPUB 3 -->
</package>

---

1. The <package> Element

The root element that wraps everything.

Required Attributes:

• xmlns: Must be "http://www.idpf.org/2007/opf"
• version: For EPUB 3, use "3.0" (or "3.1", "3.2", "3.3" for specific versions)
• unique-identifier: References the id attribute of the primary dc:identifier element in metadata

Optional Attributes:

• xml:lang: Language of the package document itself (e.g., "en")
• dir: Text direction ("ltr" or "rtl")
• prefix: For declaring custom vocabulary prefixes

Example:

<package xmlns="http://www.idpf.org/2007/opf" 
         version="3.0" 
         unique-identifier="pub-id"
         xml:lang="en"
         prefix="rendition: http://www.idpf.org/vocab/rendition/#">

---

2. The <metadata> Section

Contains all publication metadata using Dublin Core and EPUB-specific elements.

Namespace Declarations

Always include these namespaces in the metadata element:

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">

Required Metadata Elements

<dc:title> - Title

At least one title is required.

<dc:title>The Great Novel</dc:title>

For multiple titles or title types, use refinements:

<dc:title id="main-title">The Great Novel</dc:title>
<meta refines="#main-title" property="title-type">main</meta>

<dc:title id="subtitle">A Story of Adventure</dc:title>
<meta refines="#subtitle" property="title-type">subtitle</meta>
<meta refines="#subtitle" property="display-seq">2</meta>

<dc:language> - Language

RFC 5646 language code (required).

<dc:language>en-US</dc:language>
<dc:language>fr</dc:language> <!-- Multiple languages supported -->

<dc:identifier> - Unique Identifier

At least one required. The primary identifier's id must match the unique-identifier in the <package> element.

<dc:identifier id="pub-id">urn:isbn:978-0-123456-78-9</dc:identifier>
<dc:identifier id="pub-id">urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890</dc:identifier>

Common identifier schemes:

• ISBN: urn:isbn:978-0-123456-78-9
• UUID: urn:uuid:12345678-1234-1234-1234-123456789012
• DOI: urn:doi:10.1000/xyz123
• URL: https://example.com/books/mybook

<meta property="dcterms:modified"> - Last Modified Date

Required in EPUB 3. Must be in ISO 8601 format with UTC timezone.

<meta property="dcterms:modified">2024-10-22T14:30:00Z</meta>

Optional Dublin Core Elements

<dc:creator> - Author

<dc:creator id="author1">Jane Smith</dc:creator>
<meta refines="#author1" property="role" scheme="marc:relators">aut</meta>
<meta refines="#author1" property="file-as">Smith, Jane</meta>
<meta refines="#author1" property="display-seq">1</meta>

<dc:creator id="author2">John Doe</dc:creator>
<meta refines="#author2" property="role" scheme="marc:relators">aut</meta>
<meta refines="#author2" property="file-as">Doe, John</meta>
<meta refines="#author2" property="display-seq">2</meta>

Common MARC relator codes:

• aut: Author
• edt: Editor
• ill: Illustrator
• trl: Translator
• nrt: Narrator

<dc:contributor> - Contributor

Same format as creator, for contributors other than primary authors.

<dc:contributor id="editor">Alice Johnson</dc:contributor>
<meta refines="#editor" property="role" scheme="marc:relators">edt</meta>

<dc:publisher> - Publisher

<dc:publisher>Acme Publishing House</dc:publisher>

<dc:date> - Publication Date

ISO 8601 format (YYYY, YYYY-MM, or YYYY-MM-DD).

<dc:date>2024-10-22</dc:date>

<dc:subject> - Subject/Keywords

<dc:subject>Fiction</dc:subject>
<dc:subject>Science Fiction</dc:subject>
<dc:subject>Adventure</dc:subject>

With authority refinement:

<dc:subject id="subject1">Science Fiction</dc:subject>
<meta refines="#subject1" property="authority">BISAC</meta>
<meta refines="#subject1" property="term">FIC028000</meta>

<dc:description> - Description

<dc:description>A thrilling adventure across space and time, where heroes must face impossible odds...</dc:description>

<dc:rights> - Copyright Information

<dc:rights>Copyright © 2024 Jane Smith. All rights reserved.</dc:rights>

<dc:source> - Source Publication

For derivative works.

<dc:source>urn:isbn:978-0-987654-32-1</dc:source>

<dc:type> - Resource Type

<dc:type>Text</dc:type>

<dc:coverage> - Coverage

Spatial or temporal topic.

<dc:coverage>New York City, 1920s</dc:coverage>

<dc:relation> - Related Resource

<dc:relation>urn:isbn:978-0-111111-11-1</dc:relation>

EPUB-Specific Metadata

Cover Image

<meta name="cover" content="cover-image"/>

This references a manifest item with id="cover-image".

Series Information

<meta property="belongs-to-collection" id="series">The Epic Trilogy</meta>
<meta refines="#series" property="collection-type">series</meta>
<meta refines="#series" property="group-position">2</meta>

Reading Progression Direction

<meta property="rendition:layout">reflowable</meta>
<meta property="rendition:orientation">auto</meta>
<meta property="rendition:spread">auto</meta>

For right-to-left texts:

<spine page-progression-direction="rtl">

Custom Metadata with <meta>

EPUB 3 uses <meta> elements with property attributes for extensibility:

<meta property="schema:accessMode">textual</meta>
<meta property="schema:accessMode">visual</meta>
<meta property="schema:accessibilityFeature">alternativeText</meta>
<meta property="schema:accessibilityHazard">none</meta>
<meta property="schema:accessibilitySummary">This publication conforms to WCAG 2.0 Level AA.</meta>

---

3. The <manifest> Section

Lists every file that is part of the publication (except mimetype and META-INF/container.xml).

Basic Structure

<manifest>
  <item id="cover" href="cover.xhtml" media-type="application/xhtml+xml"/>
  <item id="cover-image" href="images/cover.jpg" media-type="image/jpeg" properties="cover-image"/>
  <item id="chapter1" href="chapter1.xhtml" media-type="application/xhtml+xml"/>
  <item id="style" href="style.css" media-type="text/css"/>
  <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>
  <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>
</manifest>

<item> Attributes

Required Attributes:

• id: Unique identifier for this item (used by spine)
• href: Relative path to the file
• media-type: MIME type of the file

Optional Attributes:

• properties: Space-separated list of properties
• fallback: ID of fallback item for foreign resources
• media-overlay: ID of media overlay document

Common Media Types

File Type	Media Type
XHTML	application/xhtml+xml
CSS	text/css
JavaScript	application/javascript or text/javascript
JPEG	image/jpeg
PNG	image/png
GIF	image/gif
SVG	image/svg+xml
MP3	audio/mpeg
MP4 Audio	audio/mp4
MP4 Video	video/mp4
WebM	video/webm
TrueType Font	font/ttf or application/font-sfnt
OpenType Font	font/otf or application/font-sfnt
WOFF	font/woff
WOFF2	font/woff2
NCX	application/x-dtbncx+xml
SMIL	application/smil+xml

Item Properties

Properties provide additional information about manifest items.

cover-image

Identifies the publication's cover image.

<item id="cover-img" href="images/cover.jpg" media-type="image/jpeg" properties="cover-image"/>

nav

Identifies the EPUB Navigation Document (required in EPUB 3).

<item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>

mathml

Contains MathML markup.

<item id="chapter5" href="chapter5.xhtml" media-type="application/xhtml+xml" properties="mathml"/>

remote-resources

References resources hosted outside the EPUB container.

<item id="chapter3" href="chapter3.xhtml" media-type="application/xhtml+xml" properties="remote-resources"/>

scripted

Contains scripting/interactivity.

<item id="interactive" href="game.xhtml" media-type="application/xhtml+xml" properties="scripted"/>

svg

Contains inline SVG.

<item id="diagram" href="diagram.xhtml" media-type="application/xhtml+xml" properties="svg"/>

switch

Contains epub:switch elements.

<item id="chapter2" href="chapter2.xhtml" media-type="application/xhtml+xml" properties="switch"/>

Properties can be combined:

<item id="chapter7" href="chapter7.xhtml" media-type="application/xhtml+xml" properties="mathml svg scripted"/>

---

4. The <spine> Section

Defines the default reading order of the publication.

Basic Structure

<spine page-progression-direction="ltr">
  <itemref idref="cover"/>
  <itemref idref="titlepage"/>
  <itemref idref="toc"/>
  <itemref idref="chapter1"/>
  <itemref idref="chapter2"/>
  <itemref idref="chapter3"/>
  <itemref idref="about-author" linear="no"/>
</spine>

<spine> Attributes

toc (EPUB 2 compatibility)

References the NCX file for EPUB 2 compatibility:

<spine toc="ncx">

page-progression-direction

Reading direction for the entire publication:

• ltr: Left-to-right (default)
• rtl: Right-to-left (for Arabic, Hebrew, etc.)
• default: Inherit from content

<spine page-progression-direction="rtl">

<itemref> Attributes

Required:

• idref: References an <item> id from the manifest

Optional:

• linear: Whether the item is in the primary reading order

  • yes (default): In primary reading order
  • no: Auxiliary content (appendices, notes)

  <itemref idref="footnotes" linear="no"/>
  

• properties: Space-separated list of properties

  • page-spread-left: Force left page in spread
  • page-spread-right: Force right page in spread
  • page-spread-center: Full spread (both pages)
  • rendition:layout-pre-paginated: Fixed layout
  • rendition:layout-reflowable: Reflowable (default)
  • rendition:orientation-landscape: Landscape orientation
  • rendition:orientation-portrait: Portrait orientation
  • rendition:spread-none: No spread
  • rendition:spread-auto: Auto spread (default)
  • rendition:spread-both: Always spread
  • rendition:page-spread-center: Center spread

  <itemref idref="cover" properties="rendition:layout-pre-paginated rendition:spread-none"/>
  <itemref idref="chapter1" properties="page-spread-right"/>
  

---

5. The <guide> Section (Deprecated)

Note: The <guide> element is deprecated in EPUB 3. Use the Navigation Document's landmarks nav instead. However, it's often included for EPUB 2 backward compatibility.

<guide>
  <reference type="cover" title="Cover" href="cover.xhtml"/>
  <reference type="toc" title="Table of Contents" href="toc.xhtml"/>
  <reference type="text" title="Start" href="chapter1.xhtml"/>
</guide>

Common reference types:

• cover: Cover page
• title-page: Title page
• toc: Table of contents
• index: Index
• glossary: Glossary
• acknowledgements: Acknowledgements
• bibliography: Bibliography
• colophon: Colophon
• copyright-page: Copyright page
• dedication: Dedication
• epigraph: Epigraph
• foreword: Foreword
• loi: List of illustrations
• lot: List of tables
• notes: Notes
• preface: Preface
• text: Start of main content

---

Complete Example

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf" 
         version="3.0" 
         unique-identifier="pub-id"
         xml:lang="en"
         prefix="rendition: http://www.idpf.org/vocab/rendition/#">
  
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <!-- Required Elements -->
    <dc:identifier id="pub-id">urn:uuid:12345678-1234-1234-1234-123456789012</dc:identifier>
    <dc:title>The Dissonance</dc:title>
    <dc:language>en</dc:language>
    <meta property="dcterms:modified">2024-10-22T14:30:00Z</meta>
    
    <!-- Creator with Metadata -->
    <dc:creator id="creator1">J. Rogers</dc:creator>
    <meta refines="#creator1" property="role" scheme="marc:relators">aut</meta>
    <meta refines="#creator1" property="file-as">Rogers, J.</meta>
    
    <!-- Publication Info -->
    <dc:publisher>Independent Publishing</dc:publisher>
    <dc:date>2024-10-22</dc:date>
    <dc:rights>Copyright © 2024 J. Rogers. All rights reserved.</dc:rights>
    
    <!-- Description and Subjects -->
    <dc:description>A mind-bending journey through alternate realities...</dc:description>
    <dc:subject>Science Fiction</dc:subject>
    <dc:subject>Thriller</dc:subject>
    
    <!-- Cover -->
    <meta name="cover" content="cover-image"/>
    
    <!-- Series Information -->
    <meta property="belongs-to-collection" id="series1">The Reality Trilogy</meta>
    <meta refines="#series1" property="collection-type">series</meta>
    <meta refines="#series1" property="group-position">1</meta>
    
    <!-- Accessibility Metadata -->
    <meta property="schema:accessMode">textual</meta>
    <meta property="schema:accessibilityFeature">tableOfContents</meta>
    <meta property="schema:accessibilityHazard">none</meta>
  </metadata>
  
  <manifest>
    <!-- Navigation -->
    <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>
    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>
    
    <!-- Cover -->
    <item id="cover" href="cover.xhtml" media-type="application/xhtml+xml"/>
    <item id="cover-image" href="images/cover.jpg" media-type="image/jpeg" properties="cover-image"/>
    
    <!-- Content -->
    <item id="titlepage" href="titlepage.xhtml" media-type="application/xhtml+xml"/>
    <item id="copyright" href="copyright.xhtml" media-type="application/xhtml+xml"/>
    <item id="chapter1" href="chapter1.xhtml" media-type="application/xhtml+xml"/>
    <item id="chapter2" href="chapter2.xhtml" media-type="application/xhtml+xml"/>
    <item id="chapter3" href="chapter3.xhtml" media-type="application/xhtml+xml"/>
    
    <!-- Styles and Resources -->
    <item id="stylesheet" href="css/style.css" media-type="text/css"/>
    <item id="font1" href="fonts/OpenSans-Regular.ttf" media-type="font/ttf"/>
  </manifest>
  
  <spine toc="ncx">
    <itemref idref="cover"/>
    <itemref idref="titlepage"/>
    <itemref idref="nav"/>
    <itemref idref="copyright" linear="no"/>
    <itemref idref="chapter1"/>
    <itemref idref="chapter2"/>
    <itemref idref="chapter3"/>
  </spine>
  
  <guide>
    <reference type="cover" title="Cover" href="cover.xhtml"/>
    <reference type="toc" title="Table of Contents" href="nav.xhtml"/>
    <reference type="text" title="Start Reading" href="chapter1.xhtml"/>
  </guide>
  
</package>

---

Best Practices

1. Always validate your EPUB: Use tools like EPUBCheck to ensure compliance
2. Include EPUB 2 compatibility: Add NCX file and guide section for older readers
3. Use semantic metadata: Add detailed creator, subject, and accessibility metadata
4. Declare all properties: Use manifest item properties to help reading systems optimize display
5. Keep identifiers stable: Don't change the unique identifier between editions
6. Use ISO 8601 dates: Always use standard date formats
7. Include accessibility metadata: Schema.org accessibility properties help all users
8. Test on multiple devices: Different reading systems interpret OPF files differently

---

Common Pitfalls

• Forgetting dcterms:modified: This is required in EPUB 3
• Wrong unique-identifier: Must match an identifier's id attribute
• Missing nav item: EPUB 3 requires a Navigation Document
• Incorrect media types: Use standard MIME types
• Invalid properties values: Only use defined property values
• Orphaned spine items: Every itemref must reference a manifest item
• Manifest items not in spine: Content files should be in spine (with linear="no" if auxiliary)

---

Resources

• EPUB 3.3 Specification: https://www.w3.org/TR/epub-33/
• EPUBCheck Validator: https://github.com/w3c/epubcheck
• IDPF Structural Semantics Vocabulary: http://www.idpf.org/epub/vocab/structure/
• MARC Relator Codes: https://www.loc.gov/marc/relators/relaterm.html