Publishing Technical Documents with ePub

Prerelease Version

Open Package Format

The Open Package Format (OPF) is an XML scheme that makes up the bulk of the ePub standard. There are two versions of the format still in use, version 2.x and version 3.x. The package document for version 3.x is described in detail on this page while the version for 2.x is described here. If you want a rough overview of the changes between the two, you can view this page.

Obviously, you aren’t reading this book for a few links to the documentation. This chapter will break down both versions of OPF and address common issues when creating these files.

I don’t expect most readers will want to plough straight through this chapter, or the standards documents for that matter, but studying example OPF files along with a complete reference is the best way to make sense of the file format. And it should help you later on when you are creating OPF files of your own.

The Whole Package

In both version 2.x and 3.x, the XML consists of a parent element <package> with three child elements: <metadata> which contains data about the ePub, <manifest> which contains a listing of the files used by the ePub, and <spine> which contains the reading order that the ePub Reader (the Reader) should use to navigate the content as well as other important navigation files.

<package> element

Version 2.x example:

<package xmlns:opf="http://www.idpf.org/2007/opf" 
         xmlns:dcterms="http://purl.org/dc/terms/"
         xmlns:dc="http://purl.org/dc/elements/1.1/"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xmlns="http://www.idpf.org/2007/opf" 
         version="2.0" 
         unique-identifier="id">

Version 3.x example:

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

The package element has two required attributes: version, which is either 2.0 or 3.0 depending on which OPF you’re using, and unique-identifier, which contains the id of an <dc:identifier> element that has some sort of unique id for the ePub. There are number of different schemes you can use depending upon your work flow, but ideally there should only be one unique identifier per ePub document.

There are a number of attributes beginning with xmlns: which are not required by the specification, but are important when trying to validate the XML itself. These are needed if you use elements that are defined in other specifications (like Dublin Core) in your OPF file. If you don’t put include these attributes in your file, and you use tags that contain dc:, you will probably get an error during validation.

<metadata> element

Example:

<metadata> . . . </metadata>

This is a wrapper element in both versions of the spec. You may see xmlns: attributes here, instead of the parent elements, but these are not strictly required the spec, and are used by the XML parser instead.

How to handle the elements inside <metadata> is one of the less clear parts of the specification. This may be due to compromises between research-oriented stakeholders, that want the ability to add as much descriptive metadata as possible, and other stakeholders (e.g. trade publishers), who don’t care as much about detailed metadata and just want something that doesn’t mess up their workflows. How much of these elements you include will likely depend on your own needs, though there are a few elements that are required by the spec.

Required elements

We will list required metadata separately from the optional, though you will probably use a mix of both types in your documents.

<dc:identifier> element

Version 2.x example

<dc:identifier id="id" opf:scheme="URI">
     http://www.gutenberg.org/ebooks/832
</dc:identifier>

Version 3.x example

<dc:identifier id="pub-id">
     http://www.gutenberg.org/ebooks/832
</dc:identifier>
<meta refines="#pub-id" property="identifier-type" scheme="marc:identifiers">
     URI
</meta>

dc:identifier is a required metadata child element in both specifications, though it is not required to appear in any particular order in the meta data. The dc: namespace prefix shows that it is used by the Dublin Core element set this also includes a list of Dublin Core terms that can be used in the meta elements. These terms and elements can all be reused as needed when building your own metadata. A few other allowable specifications include: Prism, Onix, and the Library of Congress MARC system.

The major change from 2.x to 3.x is that many of the opf: attributes have been moved into separate <meta> tags which then link back to whatever metadata element they describe. The new attributes used by these meta tags (e.g. the scheme attribute) is also more strict in the values it accepts. This may require you to refer back to the specifications document, just to figure out how to add metadata that was contained in an attribute in the 2.x Version of the spec.

That being said, the scheme property isn't actually required by the specification. If you're having trouble with the scheme you used in 2.x now working, just remove the scheme type. However if you use a scheme from a controlled list, like the Library of Congress Standard Identifiers, you need to match it to the correct prefix in order for it to validate correctly. Confusing, I know, but most common cases are fairly well documented.

Also note that id is a required attribute for the dc:identifier element that is referred to by the root <package> element in its unique-identifier attribute. id is also required if you have other meta elements that refer back to an element. Also note that you are allowed to have more than one dc:identifier element, as long as you have only one that is used as the unique-identifier for the <package> element.

<dc:title> element

Simple 2.x/3.x Example:

<dc:title>Robin Hood</dc:title>

Optional 3.x example:

<dc:title id="t1">A Dictionary of Modern English Usage</dc:title>
<meta refines="#t1" property="title-type">main</meta>

dc:title is a required element. You can have more than one title in both 2.x and 3.x although there are additional limitations if you have multiple titles in 3.x. Reader apps will often ignore multiple titles in favor of the first title you put in the OPF.

<dc:language> element

Version 2.x example:

<dc:language xsi:type="dcterms:RFC4646">en</dc:language>

Version 3.x example:

<dc:language>en</dc:language>

dc:language is a required element. You are allowed more than one language element in both 2.x and 3.x. The value of the element describes the language most commonly used by the document. This value is a simple string taken from an Internet standard for language names. Which standard you use depends (somewhat) on whether you are using Version 2.x or 3.x.

In Version 2.x, the standard was originally assumed to be defined in the RFC 3066 standard. Other standards were allowed, as long as you specified what they were (which is why the xsi:type attribute is used in the example). Version 3.x has used a successor standard, RFC 4646, from the beginning.

If you need to look up what language code to use, for example if your document is in Ancient Greek, you start with the ISO 639 code for the root language (see this page), then add hyphens with additional codes if you’re using a special script for that language or some dialect. Look up the specification for RFC 4646 if you need even more detail, but this is overkill for most use cases.

Optional metadata elements

These elements are optional, but many of these are used by the Reader to display the Author and other important information.

<dc:creator> element

Version 2.x example:

<dc:creator opf:file-as="McSpadden, J. Walker (Joseph Walker)" opf:role="aut">
     J. Walker McSpadden
</dc:creator>

Version 3.x example:

<dc:creator id="creator">J. Walker McSpadden</dc:creator>
<meta refines="#creator" property="file-as">
     McSpadden, J. Walker (Joseph Walker)
</meta>
<meta refines="#creator" property="role" scheme="marc:relators">aut</meta>

dc:creator is used to represent the name of a person, organization, etc. responsible for the creation of the content of a Publication. You can have more than one dc:creator element if, for example, you have multiple authors, though you should use a different element from dc:creator if you have secondary contributors (like an illustrator).

In Version 3.x, you can also refine that property using additional meta elements to show the role, or which name you should use if generating a sorted list of authors, etc. This is different from Version 2.x, where opf: attributes were added directly to the creator element. When refining an element in Version 3.x, you will need to use an id attribute in the dc:creator element to link the meta with the element it is describing.

dc:creator also has an optional xml:lang attribute that can be useful if you have a single author’s name in multiple languages, or if the language you are using is different from the one described in the dc:language element. Version 3.x also uses the optional dir attribute to show whether than script being used is left-to-right or right-to-left.

<dc:contributor> element

dc:contributor is used to represent the name of a person, organization, etc. that played a secondary role in the creation of the content of a Publication. In all other respects it is identical to the previous <dc:creator> element.

<dc:date> element

Version 2.x example:

<dc:date opf:event="publication">2006-01-21</dc:date>
<dc:date opf:event="conversion">2013-02-06T21:26:43.405225+00:00</dc:date>

Version 3.x example:

<dc:date>2006-01-21</dc:date>
<meta property="dcterms:modified">2015-04-27T06:08:34Z</meta>

dc:date is used to describe a single publication date in Version 3.x and is only allowed once but can appear multiple times with different contexts in Version 2.x. The opf:event attribute has been scrapped in version 3.x though you can add additional dates using a meta element with dcterms: if you want to. Both versions use the ISO 8601 date format, which basically specifies the order the elements in the date must appear, but allows you to only include the year or month, if that is all you have to go by. See this page for details.

<dc:source> element

Version 2.x example:

<dc:source id="src-id">urn:isbn:9780375704024</dc:source>

Version 3.x example:

<dc:source id="src-id">urn:isbn:9780375704024</dc:source>
<meta refines="#src-id" property="identifier-type" scheme="onix:codelist5">
     15</meta>

The dc:source element must only be used to specify the identifier of the source publication from which this EPUB Publication is derived. Only one instance of this element is allowed.

<dc:publisher> element

dc:publisher is used to represent the name of a person, organization, etc. that is responsible for making the resource available.

<dc:type> element

According to the spec, the dc:type element is used to indicate that the given Publication is of a specialized type (e.g., annotations packaged in EPUB format or a dictionary). Likely included to conform to Dublin Core, but only has specialized use cases.

<dc:coverage> element

Defined as the extent or scope of the publication’s content by the spec. Likely included to conform to Dublin Core, but only has specialized use cases.

<dc:description> element

Helpfully defined as “Description of the publication’s content.” May include a copy of an abstract or something else. Included as part of the Dublin Core.

<dc:format> element

“The media type or dimensions of the resource.” Best practice is to use something like a MIME type.

<dc:relation> element

Defined as “an identifier of an auxiliary resource and its relationship to the publication.” This is most likely for supplemental publications or other publications that are directly related. Likely included to conform to Dublin Core, but only has specialized use cases.

<dc:rights> element

Version 2.x/3.x example:

<dc:rights>Public domain in the USA.</dc:rights>

A statement about rights, or a reference to one. This is separate from any copyright page and may (or may not) be used by the Reader or a distribution platform. Most likely not, since the use of copy protection schemes and/or payment methods will be stored internally to any App or website.

<dc:subject> element

Version 2.x/3.x example:

<dc:subject>Robin Hood (Legendary character) -- Legends</dc:subject>
<dc:subject>Folklore -- England</dc:subject>

A topic of the content of the resource, typically expressed as keywords, key phrases or classification codes. Multiple subjects are allowed. Included to conform to Dublin Core, but likely ignored by most Readers. May be used by some distribution platforms.

<meta> elements

<meta property="ibooks:specified-fonts">true</meta>

Many ePub Readers have custom properties that you can add to the meta data to improve the experience on those platforms. These are, technically, not part of the ePub spec but can still be important. For example, if you want to tell iBooks to use your custom fonts, and you’re using Version 3.x, you should add the example meta property to the metadata. See iBooks Asset Guide for iBooks specific details, or consult the documentation for your platform of choice.

Manifest Elements

These elements exist to help the Reader and related software keep track of all of the content used in the ePub. This section is essentially a list of all of the files used by the ePub content.

<manifest> element

Version 2.x/3.x example:

<manifest> . . . </manifest>

This element is a wrapper for the entire section. It can have an optional id attribute.

<item> element

Version 2.x examples:

<item href="css/epub-serif.css" id="item0" media-type="text/css"/>
<item href="html/chapter-1.xhtml" id="item1" 
      media-type="application/xhtml+xml"/>
<item href="toc.ncx" id="ncx" media-type="application/x-dtbncx+xml"/>
<item href="cover-img.jpg" id="cover-image" media-type="image/jpeg" />

Version 3.x examples:

<item href="css/epub-serif.css" id="item0" media-type="text/css"/>
<item href="html/chapter-1.xhtml" id="chapter-1" 
      media-type="application/xhtml+xml"/>
<item href="toc.ncx" id="ncx" media-type="application/x-dtbncx+xml"/>
<item href="toc.xhtml" id="toc" media-type="application/xhtml+xml" 
      properties="nav"/>
<item href="cover-img.jpg" id="cover-image" media-type="image/jpeg" 
      properties="cover-image"/>

item elements contain a number of required attributes: href which points to the file’s location in the ePub archive, id which is used referred to later on in the spine elements, and media-type which is the MIME type of the file you are linking to. If the MIME type you are including is not one of the standard ePub file types then you also need a fallback attribute which contains the id of another manifest resource that the Reader can use if it is unable to read the file type. These fallback items can be chained together, if needed, as long as there is a standard ePub file type at the end of the chain.

The order of files in the manifest does not matter, however each file with a given href can only appear once in the manifest. If you attempt to list a file more than once, even with different associated ids, it will cause an error.

Version 3.x added the optional properties attribute which can be used to indicate that the given file is the navigation document, for example, by adding nav to the properties list. Multiple properties can be added to a file just by separating them with a space, for example if a file contains MathML and an SVG image, the properties attribute may look like: properties="mathml svg". A more detailed explanation of how the properties attribute works is here.

Spine Elements

These elements are an ordered list of the ePub content and refers back to the ids you created when building the manifest.

<spine> element

Version 2.x/3.x example:

<spine toc="ncx">

spine is basically a wrapper element. The main difference between 2.x and 3.x is that 2.x required an XML file known as the “Navigation Center eXtended” file which was linked to in the spine with the toc attribute. In 3.x this was superseded by an HTML file with the nav property instead though you can still add an optional .ncx file to aid compatibility with older Readers. Both files are described in the next chapter.

Version 3.x also added an optional id attribute as well as the optional page-progression-direction attribute. This last attribute is needed if you are using a right-to-left writing system and want the pages to appear in the correct reading order. Add page-progression-direction="rtl" to indicate a right-to-left system. Use “ltr” to indicate left-to-right and “default” to indicate that you should just use whatever the default is for the Reader. See Note on Right-to-Left for more details.

<itemref> element

Version 2.x/3.x examples:

<itemref idref="item1" linear="yes"/>
<itemref idref="toc" linear="no"/>

This is a list of content file ids (typically your HTML files) presented in the order they should be read. If you have content that is not part of the core text, you should add the linear="no" attribute to let the Reader know that it does not have to layout this content directly (it may be presented as a popup or something).

An XHTML navigation file, like a Table of Contents, does not exist in Version 2.x, as that version used the .ncx file instead. However, it should be included if you are using Version 3.x (and should have linear="no" as an attribute). In Version 3.x, you can also include a properties attribute. This is primarily used by Fixed Layout documents (FXL) to indicate which page a two page spread starts on (see here for more info). FXL will be covered in a future chapter, though not in great detail.

<guide> element

guide is a rarely used section that is described here for Version 2.x and is deprecated in 3.x.

Generally it has a link to the Cover, Table of Contents, and start of the document. Most reading systems can cope without it, but I’m including this for completeness sake.

Cover Pages

In many ways, cover pages are no different from other content types. You need to add a reference to them in the spine, manifest, and navigation. However you should also add additional attributes so that the Reader knows that it is a cover and not just part of the rest of the content.

  1. Create an XHTML page for the cover page. This may only be a mostly blank XHTML with just a link to the image, but it’s still a good idea to have it.
  2. Add the cover XHTML page and the cover image to the <manifest> element with unique ids and the appropriate media-type. Add properties="cover-image" to the element describing the cover image if you are using Version 3.x.
  3. Add the cover XHTML page to the start of the <spine> element with the appropriate id.
  4. Add the cover XHTML page to the <guide> element if you are using one.
  5. Add the cover XHTML page to the nav document (Chapter 4) in the appropriate place depending on whether you’re using Version 2.x or 3.x.

A Note on Right-to-Left Writing Systems

Many ePub Readers have support for Right-to-Left Systems, but need to be explicitly told to use this. To do this you must:

  1. Use Version 3.x of the ePub standard.
  2. Add page-progression-direction="rtl" to the spine element in the OPF file.
  3. Add dir="rtl" to each body element in your ePub HTML content that uses a Right-to-Left system.

Previous

Next

Table of Contents