Manifest fallbacks

Manifest fallbacks are a feature of the [=package document=] that create a manifest fallback chain for a [=publication resource=], allowing [=reading systems=] to select an alternative format they can render.

Fallback chains are created using the fallback attribute on [=EPUB Manifest | manifest=] [^item^] elements. This attribute references the ID [[xml]] of another manifest item that is a fallback for the current item. The ordered list of all the references that a reading system can reach, starting from a given item's fallback attribute, represents both the full and preferred fallback chain for that item.

There are two cases for manifest fallbacks:

Spine fallbacks

A [=foreign content document=] MUST specify a fallback chain that MUST include at least one [=EPUB content document=] to ensure that reading systems can always render the [=EPUB spine | spine=] item.

EPUB content documents MAY specify a fallback. For example, to provide a fallback for scripted content.

When a fallback chain includes more than one EPUB content document, the properties attribute can be used to differentiate the purpose of each.

Content fallbacks

The original reason for defining a content fallback mechanism was to handle foreign resource images in the [[html]] [^img^] element. As HTML now has intrinsic fallback mechanisms for images, such as the [^img/srcset^] attribute and [^source^] element, the use of content fallbacks is strongly discouraged.

When elements that reference [=foreign resources=] do not have intrinsic fallback capabilities, a content fallback MUST be provided. In this case, the fallback chain MUST contain at least one [=core media type resource=].

Manifest fallbacks MAY also be provided for core media type resources. For example, to allow reading systems to select from more than one image format.

Regardless of the type of manifest fallback specified, fallback chains MUST NOT contain self-references or circular references to item elements in the chain.

Intrinsic fallbacks

The following sections provide additional clarifications about the intrinsic fallback requirements of specific elements.

File and directory structure

The virtual file system for the [=OCF abstract container=] MUST have a single common [=root directory=] for all the contents of the container.

The OCF abstract container MUST include a directory for configuration files named META-INF that is a direct child of the container's root directory. Refer to for the requirements for the contents of this directory.

The file name mimetype in the root directory is reserved for use by [=OCF ZIP containers=], as explained in .

Files in the META-INF directory and the mimetype file are not [=publication resources=] so MUST NOT be listed in the [=EPUB manifest|manifest=].

All other files within the OCF abstract container MAY be stored in any location descendant from the root directory provided they are not within the META-INF directory. [=EPUB publications=] MUST NOT contain references to files in the META-INF directory.

File paths and file names

In the context of the [=OCF abstract container=], [=file paths=] and [=file names=] are [=scalar value strings=] [[infra]] (i.e., their values are case sensitive).

In addition, the following restrictions are designed to allow file paths and file names to be used without modification on most operating systems:

• File names MUST NOT exceed 255 bytes.

• The file paths for any directory or file within the OCF abstract container MUST NOT exceed 65535 bytes.

• File names MUST NOT use the following [[unicode]] characters as commonly used operating systems might not support these characters consistently:

  • SOLIDUS: / (U+002F)

  • QUOTATION MARK: " (U+0022)

  • ASTERISK: * (U+002A)

  • FULL STOP as the last character: . (U+002E)

  • COLON: : (U+003A)

  • LESS-THAN SIGN: < (U+003C)

  • GREATER-THAN SIGN: > (U+003E)

  • QUESTION MARK: ? (U+003F)

  • REVERSE SOLIDUS: \ (U+005C)

  • VERTICAL LINE: | (U+007C)

  • DEL (U+007F)

  • C0 range (U+0000 … U+001F)

  • C1 range (U+0080 … U+009F)

  • Private Use Area (U+E000 … U+F8FF)

  • All Unicode Non Characters, specifically:

    • The 32 contiguous characters in the Basic Multilingual Plane (U+FDD0 … U+FDEF)

    • The last two code points of the Basic Multilingual Plane (U+FFFE and U+FFFF)

    • The last two code points at the end of the Supplementary Planes (U+1FFFE, U+1FFFF … U+EFFFE, U+EFFFF)

  • Specials (U+FFF0 … U+FFFF)

  • Supplementary Private Use Area-A (U+F0000 … U+FFFFF)

  • Supplementary Private Use Area-B (U+100000 … U+10FFFF)

  The Unicode Character Database [[uax44]] includes a list of deprecated characters. It is also advised to avoid these characters as it is expected that [=EPUB conformance checkers=] will flag their use.

• For compatibility with older [=reading systems=], file names SHOULD NOT contain SPACE (U+0020) characters.

• All file names within the same directory MUST be unique following Unicode canonical normalization [[uax15]] and then full case folding [[unicode]]. (Refer to Unicode Canonical Case Fold Normalization Step [[?charmod-norm]] for more information.)

Deriving file paths

To derive the file path, given a file or directory file in the OCF abstract container, apply the following steps (expressed using the terminology of [[infra]]):

1. Let path be an empty [=list=].
2. Let current be file.
3. While current is not the [=root directory=]:
   1. [=list/prepend=] the [=file name=] of current to path;
   2. set current to the parent directory of current.
4. Return the concatenation of path using the U+002F (/) character.

URLs in the OCF abstract container

The [=container root URL=] is the [=URL=] [[url]] of the [=root directory=]. Although the container root URL is implementation-specific, it MUST have the following properties:

• The result of parsing "/" with the [=container root URL=] as base is the [=container root URL=].
• The result of parsing ".." with the [=container root URL=] as base is the [=container root URL=].

The [=content URL=] of a file or directory in the [=OCF abstract container=] is the result of [=url parser | parsing=] the file's [=file path=] with the container root URL as base.

A string url is a valid-relative-ocf-URL-with-fragment string if it is a [=path-relative-scheme-less-url string=], optionally followed by U+0023 (#) and a [=url-fragment string=], and if the following steps return true:

1. Set the [=container root URL=] to https://a.example.org/A/.

   Explanation

   The goal of the algorithm is to detect whether url could be seen as "leaking" outside the container. To do that, the standard [=url parser | URL parsing algorithm=] is used with an artificial root URL; the detection of the "leak" is done by comparing the result of the parsing with the presence of the first test path segment (A). (Note that the artificial container root URL wilfully violates, for the purpose of this algorithm, the required properties by using that first test path segment.)

2. Let base be the base URL that is used to parse url as defined by the context (document or environment) where url is used, and according to the content URL of the [=package document=] (see ).

   Explanation

   In the case of a URL in the package document the base variable is set to the content URL of the package document. In the case of a document within the META-INF directory, the base variable is set to the container root URL (see ). In the case of a URL in an [=XHTML content document=], the base URL used for parsing is defined by the HTML standard. Typically, it will be the content URL of the content document (unless the discouraged base element is used).

3. Let testURLRecord be the result of applying the [=URL parser=] to url, with base.
4. Let testURLStringA be the result of applying the [=URL Serializer=] to testURLRecord.

5. Set the [=container root URL=] to https://b.example.org/B/.

   Explanation

   The reasons to repeat the same steps twice with different, and artificial, settings of the container root URL is to avoid collision which can occur if the url string also includes /A/. Consider, for example, the case where url is ../../A/doc.xhtml.

6. Set base to be the base URL that is used to parse url as defined by the context (document or environment) where url is used, and according to the content URL of the package document (see ).
7. Set testURLRecord to be the result of applying the [=URL parser=] to url, with base.
8. Let testURLStringB be the result of applying the [=URL Serializer=] to testURLRecord.

9. If testURLStringA does not start with https://a.example.org/ or testURLStringB does not start with https://b.example.org/, return true.

   Explanation

   If any of the result does not share the test URL host, it means that url, or its base URL (for example, in HTML, if it is explicitly set with the base element), was absolute and points outside the container. This is acceptable.

10. If testURLStringA starts with https://a.example.org/A/ and testURLStringB starts with https://b.example.org/B/, return true.

    Explanation

    The presence of the first test path segments (A, respectively B) indicate that the URL doesn't leak outside the container.

11. Return false.

In the OCF abstract container, any URL string MUST be an [=absolute-url-with-fragment string=] or a [=valid-relative-ocf-URL-with-fragment string=].

In addition, all [=relative-URL-with-fragment strings=] [[url]] MUST, after parsing, be equal to the content URL of an existing file in the OCF abstract container.

META-INF directory

ZIP file requirements

An [=OCF ZIP container=] uses the ZIP format as specified by [[zip]], but with the following constraints and clarifications:

• The contents of the OCF ZIP container MUST be a conforming OCF abstract container.

• OCF ZIP containers MUST NOT use the features in the ZIP application note [[zip]] that allow ZIP files to be spanned across multiple storage media or be split into multiple files.

• OCF ZIP containers MUST include only stored (uncompressed) and Deflate-compressed ZIP entries within the ZIP archive.

• OCF ZIP containers MAY use the ZIP64 extensions defined as "Version 1" in section V, subsection G of the application note [[zip]] and SHOULD use only those extensions when the content requires them.

• OCF ZIP containers MUST NOT use the encryption features defined by the ZIP format; instead, encryption MUST be done using the features described in .

• OCF ZIP containers MUST encode file system names using UTF-8 [[unicode]].

The following constraints apply to specific fields in the OCF ZIP container archive:

• In the local file header table, the version needed to extract fields MUST be set to 10, 20 or 45 to match the maximum version level needed by the given file (e.g., 20 for Deflate, 45 for ZIP64).

• In the local file header table, the compression method field MUST be set to 0 or 8.

OCF ZIP container media type identification

The mimetype file MUST be the first file in the [=OCF ZIP container=]. In addition:

• The contents of the mimetype file MUST be the MIME media type [[rfc2046]] string application/epub+zip encoded in US-ASCII [[us-ascii]].
• The mimetype file MUST NOT contain any leading or trailing padding or whitespace.
• The mimetype file MUST NOT begin with the Unicode byte order mark U+FEFF.
• The mimetype file MUST NOT be compressed or encrypted.
• The mimetype file MUST NOT include an extra field in its ZIP header.

Obfuscation key

The key used in the obfuscation algorithm MUST be derived the from the [=unique identifier=].

All whitespace characters, as defined in section 2.3 of the XML 1.0 specification [[xml]], MUST be removed from this identifier — specifically, the Unicode code points U+0020, U+0009, U+000D and U+000A.

A SHA-1 digest of the UTF-8 representation of the resulting string, as specified by the Secure Hash Standard [[fips-180-4]], MUST then be generated. This digest can then be used as the key for the algorithm.

Obfuscation algorithm

The algorithm employed to obfuscate fonts consists of modifying the first 1040 bytes (~1KB) of the font file. (In the unlikely event that the font file is less than 1040 bytes, this process will modify the entire file.)

To obfuscate the original data, store, as the first byte of the embedded font, the result of performing a logical exclusive or (XOR) on the first byte of the raw font file and the first byte of the obfuscation key.

Repeat this process with the next byte of source and key and continue for all bytes in the key. At this point, the process continues starting with the first byte of the key and 21st byte of the source. Once 1040 bytes are encoded in this way (or the end of the source is reached), directly copy any remaining data in the source to the destination.

Fonts MUST be obfuscated before compressing and adding them to the [=OCF ZIP container=]. Note that as obfuscation is not encryption, this requirement is not a violation of the one in to compress fonts before encrypting them.

The following pseudo-code exemplifies the obfuscation algorithm.

1. set ocf to OCF ZIP container file
2. set source to font file
3. set destination to obfuscated font file
4. set keyData to key for file
5. set outer to 0
6. while outer < 52 and not (source at EOF)
   1. set inner to 0
   2. while inner < 20 and not (source at EOF)
      1. read 1 byte from source (Assumes read advances file position)
      2. set sourceByte to result of read
      3. set keyByte to byte inner of keyData
      4. set obfuscatedByte to (sourceByte XOR keyByte)
      5. write obfuscatedByte to destination
      6. increment inner
      end while
   3. increment outer
   end while
7. if not (source at EOF) then
   1. read source to EOF
   2. write result of read to destination
   end if
8. Deflate destination
9. store destination as source in ocf

Specifying obfuscated fonts

Although not technically encrypted data, all obfuscated fonts MUST have an entry in the encryption.xml file accompanying the [=EPUB publication=] (see ).

An EncryptedData element MUST be specified for each obfuscated font. Each EncryptedData element MUST contain a child EncryptionMethod element whose Algorithm attribute has the value http://www.idpf.org/2008/embedding. The presence of this attribute signals the use of the algorithm described in this specification.

The CipherReference child of the CipherData element MUST list the path to the obfuscated font. As the obfuscation algorithm is restricted to fonts, the URI attribute of the CipherReference element MUST reference a Font core media type resource.

To prevent trivial copying of the embedded font to other EPUB publications, the obfuscation key MUST NOT be stored in the encryption.xml file.

The dir attribute (under-implemented)

Specifies the base direction [[bidi]] of the textual content and attribute values of the carrying element and its descendants.

Allowed values are:

• ltr — left-to-right base direction;
• rtl — right-to-left base direction; and
• auto — base direction is determined using the Unicode Bidi Algorithm [[bidi]].

Reading systems will assume the value auto when the attribute is not present or has an invalid value.

Allowed on: [^collection^], Dublin Core elements, [^meta^], and [^package^].

The href attribute

A [=valid URL string=] [[url]] that references a resource.

The URL string MUST NOT reference resources via elements in the package document (e.g., via a manifest [^item^] or spine [^itemref^] declaration).

Allowed on: [^item^] and [^link^].

The id attribute

The ID [[xml]] of the element, which MUST be unique within the document scope.

Allowed on: [^collection^], Dublin Core elements, [^item^], [^itemref^], [^link^], [^manifest^], [^meta^], [^package^], and [^spine^].

The media-type attribute

A media type [[rfc2046]] that specifies the type and format of the referenced resource.

Allowed on: [^item^] and [^link^].

The properties attribute

A space-separated list of property values.

Refer to each element's definition for the reserved vocabulary for the attribute.

Allowed on: [^item^], [^itemref^], and [^link^].

The refines attribute

Establishes an association between the current expression and the element or resource identified by its value. The value of the attribute MUST be a [=path-relative-scheme-less-URL string=], optionally followed by U+0023 (#) and a [=URL-fragment string=] that references the resource or element being described.

The refines attribute is OPTIONAL depending on the type of metadata expressed. When omitted, the element defines a primary expression.

When creating expressions about a [=publication resource=], the refines attribute SHOULD specify a fragment identifier that references the ID [[xml]] of the resource's manifest entry.

Refinement chains MUST NOT contain circular references or self-references.

Allowed on: [^link^] and [^meta^].

The xml:lang attribute

Specifies the language of the textual content and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [[xml]]. The value of each xml:lang attribute MUST be a well-formed language tag [[bcp47]].

Allowed on: [^collection^], Dublin Core elements, [^meta^], and [^package^].

The metadata element

The metadata element encapsulates meta information.

Element Name:

metadata

Usage:

REQUIRED first child of [^package^].

Attributes:

None

Content Model:

In any order:

• [^dc:identifier^] [1 or more]

• [^dc:title^] [1 or more]

• [^dc:language^] [1 or more]

• Dublin Core Optional Elements [0 or more]

• [^meta^] [1 or more]

• OPF2 meta [0 or more] (legacy)

• [^link^] [0 or more]

The [=package document=] metadata element has two primary functions:

1. to provide a minimal set of meta information for [=reading systems=] to use to internally catalogue an [=EPUB publication=] and make it available to a user (e.g., to present in a bookshelf).

2. to provide access to all rendering metadata needed to control the layout and display of the content (e.g., fixed-layout properties).

The package document does not provide complex metadata encoding capabilities. If more detailed information needs to be provided, metadata records (e.g., that conform to an international standard such as [[onix]] or are created for custom purposes) can be associated with the EPUB publication using the [^link^] element. This approach allows reading systems to process the metadata in its native form, avoiding the potential problems and information loss caused by translating to use the minimal package document structure.

In keeping with this philosophy, the package document only has the following minimal metadata requirements: it MUST contain the [[dcterms]] [^dc:title^], [^dc:identifier^], and [^dc:language^] elements together with the [[dcterms]] [^dcterms:modified^] property. All other metadata is OPTIONAL.

The [^meta^] element provides a generic mechanism for including metadata properties from any vocabulary. Although this mechanism can be used for any metadata purposes, it is typically used to include rendering and accessibility metadata defined in EPUB specifications.

Metadata values

The Dublin Core elements [[dcterms]] and [^meta^] element have mandatory [=child text content=] [[dom]]. In the descriptions for these elements, this specification refers to this content as the element's value.

These elements MUST have non-empty values after leading and trailing ASCII whitespace [[infra]] is stripped (i.e., they have to consist of at least one non-whitespace character).

Whitespace within these element values is not significant. Sequences of one or more whitespace characters are collapsed to a single space [[infra]] during processing .

Dublin Core

<metadata …>
   <dc:title>
      THE LORD OF THE RINGS
   </dc:title>
   <dc:title>
      Part One: The Fellowship of the Ring
   </dc:title>
   …
</metadata>

<metadata …>
   <dc:title>
       THE LORD OF THE RINGS, Part One:
       The Fellowship of the Ring
   </dc:title>
   …
</metadata>

The meta element

The meta element provides a generic means of including package metadata.

Element Name:

meta

Usage:

As child of the [^metadata^] element. Repeatable.

Attributes:

• dir [optional]

• id [optional]

• property [required]

• refines [optional]

• scheme [optional]

• xml:lang [optional]

Content Model:

Text

Each meta element defines a metadata expression. The property attribute takes a property data type value that defines the statement made in the expression, and the text content of the element represents the assertion. (Refer to for more information.)

This specification defines two types of metadata expressions that can be defined using the meta element:

• A primary expression is one in which the expression defined in the meta element establishes some aspect of the [=EPUB publication=]. A meta element that omits a refines attribute defines a primary expression.
• A subexpression is one in which the expression defined in the meta element is associated with another expression or resource using the refines attribute to enhance its meaning. A subexpression might refine a media clip, for example, by expressing its duration, or refine a creator or contributor expression by defining the role of the person.

Subexpressions MAY be used to refine the meaning of other subexpressions, thereby creating chains of information.

All the [[dcterms]] elements represent primary expressions, and permit refinement by meta element subexpressions.

The Meta Properties Vocabulary is the default vocabulary for use with the property attribute.

Terms from other vocabularies MAY be added as defined in .

The scheme attribute identifies the system or scheme the element's [=value=] was obtained from. The value of the attribute MUST be a property data type value that resolves to the resource that defines the scheme. The scheme attribute does not have a default vocabulary (i.e., all values require a prefix).

Last modified date

The metadata section MUST contain exactly one dcterms:modified property [[dcterms]] containing the last modification date. The [=value=] of this property MUST be an [[iso8601-1]] complete representation of a date and time of day matching the extended format:

YYYY-MM-DDThh:mm:ssZ

It is advised to update the last modified date whenever changes are made to the [=EPUB publication=].

Additional dcterms:modified properties MAY be specified in the [=package document=] metadata, but they MUST have a different subject (i.e., they require a refines attribute that references an element or resource).

The link element

The link element associates resources with an [=EPUB publication=], such as metadata records.

Element Name:

link

Usage:

As a child of [^metadata^]. Repeatable.

Attributes:

• href [required]

• hreflang [optional]

• id [optional]

• media-type [conditionally required]

• properties [optional]

• refines [optional]

• rel [required]

Content Model:

Empty

The [^metadata^] element MAY contain zero or more link elements, each of which identifies the location of a [=publication resource=] or a [=linked resource=] in its REQUIRED href attribute.

Resources referenced from the link element are [=publication resources=] only when they are:

• referenced from the [=EPUB spine | spine=]; or

• included or embedded in an [=EPUB content document=] (e.g., a metadata record serialized as RDFa [[?rdfa-core]] or as JSON-LD [[?json-ld11]] embedded in an [[html]] [^script^] element).

In all other cases (e.g., when linking to standalone [[?onix]] records), the resources referenced are not [=publication resources=] (i.e., are not subject to core media type requirements) and MUST NOT be listed in the manifest.

Although linked resources MAY be located outside the [=EPUB container=], [=reading systems=] do not have to retrieve [=remote resources=]. It is advised to consider what impact this might have on the user's reading experience before hosting them remotely.

The media-type attribute MUST be specified for all linked resources within the EPUB container. It is OPTIONAL for linked resources located outside the EPUB container as more than one media type could be served from the same URL [[url]].

The OPTIONAL hreflang attribute identifies the language of the linked resource. The value MUST be a well-formed language tag [[bcp47]].

The REQUIRED rel attribute takes a space-separated list of property values that establish the relationship the linked resource has with the EPUB publication.

The value of the media-type attribute is not always sufficient to identify the type of linked resource (e.g., many XML-based record formats use the media type "application/xml"). To aid reading systems in the identification of such generic resources, a semantic identifier MAY be specified in the properties attribute.

The Metadata Link Vocabulary is the default vocabulary for the rel and properties attributes.

Relationships and properties from other vocabularies MAY be added as defined in .

One or more linked metadata records MAY be provided.

In addition to full records, the link element MAY be used to identify individual metadata properties available in an alternative format.

The manifest element

The manifest element provides an exhaustive list of [=publication resources=] used in the rendering of the content.

Element Name:

manifest

Usage:

REQUIRED second child of [^package^], following [^metadata^].

Attributes:

id [optional]

Content Model:

[^item^] [1 or more]

With the exception of the [=package document=], the manifest MUST list all publication resources regardless of whether they are [=container resources=] or [=remote resources=].

As the package document is already identified by the container.xml file, the manifest MUST NOT specify an item element for it (i.e., a self-reference serves no purpose).

The item element

The item element represents a [=publication resource=].

Element Name:

item

Usage:

As a child of [^manifest^]. Repeatable.

Attributes:

• fallback [conditionally required]

• href [required]

• id [required]

• media-overlay [optional]

• media-type [required]

• properties [optional]

Content Model:

Empty

Each item element identifies a publication resource by the URL [[url]] in its href attribute. The value MUST be an absolute- or path-relative-scheme-less-URL string [[url]]. Each URL MUST be unique within the manifest scope after parsing.

The publication resource identified by an item element MUST conform to the applicable specification(s) as inferred from the MIME media type [[rfc2046]] provided in the media-type attribute. For [=core media type resources=], the media type designated in MUST be used.

The fallback attribute specifies the fallback for the referenced publication resource. The fallback attribute's IDREF [[xml]] value MUST resolve to another item in the manifest.

The fallback for one item MAY specify a fallback to another item, and so on, creating a chain of fallback options. Refer to for additional requirements related to the use of fallback chains.

The media-overlay attribute takes an IDREF [[xml]] that identifies the [=media overlay document=] for the resource described by this item. Refer to for more information.

The spine element

The spine element defines an ordered list of manifest item references that represent the default reading order.

Element Name:

spine

Usage:

REQUIRED third child of [^package^], following [^manifest^].

Attributes:

• id [optional]

• page-progression-direction [optional]

• toc [optional] (legacy)

Content Model:

[^itemref^] [1 or more]

The spine MUST specify at least one [=EPUB content document=] or [=foreign content document=].

All EPUB and foreign content documents that are hyperlinked to from publication resources in the spine MUST be listed in the spine, where hyperlinking encompasses any linking mechanism that requires the user to navigate away from the current resource. Common hyperlinking mechanisms include the [^a/href^] attribute of the [[html]] [^a^] and [^area^] elements and scripted links (e.g., using DOM Events and/or form elements). The requirement to list hyperlinked resources applies recursively (i.e., all EPUB and foreign content documents hyperlinked to from hyperlinked documents have to be listed, and so on.).

All EPUB and foreign content documents hyperlinked to from the [=EPUB navigation document=] MUST also be listed in the spine, regardless of whether the EPUB navigation document is included in the spine.

The page-progression-direction attribute sets the global direction in which the content flows. Allowed values are ltr (left-to-right), rtl (right-to-left) and default. When the default value is specified, no preference is being expressed and the [=reading system=] can choose the rendering direction.

Although the page-progression-direction attribute sets the global flow direction, individual EPUB content documents and parts of EPUB content documents MAY override this setting (e.g., via the writing-mode CSS property). Reading systems might also provide mechanisms to override the default direction (e.g., buttons or settings that allow the application of alternate style sheets).

The legacy toc attribute takes an IDREF [[xml]] that identifies the manifest item that represents the NCX.

The itemref element

The itemref element identifies an [=EPUB content document=] or [=foreign content document=] in the default reading order.

Element Name:

itemref

Usage:

As a child of [^spine^]. Repeatable.

Attributes:

• id [optional]

• idref [required]

• linear [optional]

• properties [optional]

Content Model:

Empty

Each itemref element MUST reference the ID [[xml]] of an [^item^] in the [=EPUB manifest | manifest=] via the IDREF [[xml]] in its idref attribute. item element IDs MUST NOT be referenced more than once.

Each referenced manifest item MUST be either a) an [=EPUB content document=] or b) a [=foreign content document=] that includes an EPUB content document in its [=manifest fallback chain=].

The linear attribute indicates whether the referenced item contains content that contributes to the primary reading order and that [=reading systems=] are expected to read sequentially ("yes"), or auxiliary content that enhances or augments the primary content that reading systems can access out of sequence ("no"). Examples of auxiliary content include notes, descriptions, and answer keys.

The linear attribute allows reading systems to distinguish content that a user needs to access as part of the default reading order from supplementary content which a reading system might, for example, present in a popup window or omit from an aural rendering.

Specifying that content is non-linear does not require reading systems to present it in a specific way; it is only a hint to the purpose. Reading systems might present non-linear content where it occurs in the spine, for example, or might skip it until users reach the end of the spine.

A linear itemref element is one whose linear attribute value is explicitly set to "yes" or that omits the attribute — reading systems will assume the value "yes" for itemref elements without the attribute. The spine MUST contain at least one linear itemref element.

As reading systems might not provide access to non-linear content while progressing through the spine, a secondary means of accessing all non-linear content MUST be provided (e.g., via hyperlinks in the content or the EPUB navigation document).

The Spine Properties Vocabulary is the default vocabulary for the properties attribute.

Terms from other vocabularies MAY be added as defined in .

The collection element

The collection element defines a related group of resources.

Element Name:

collection

Usage:

OPTIONAL sixth element of package. Repeatable.

Attributes:

• dir [optional]

• id [optional]

• role [required]

• xml:lang [optional]

Content Model:

In this order: metadata [0 or 1], ( [^collection^] [1 or more] or ( [^collection^] [0 or more], link [1 or more] ))

The collection element allows resources to be assembled into logical groups for a variety of potential uses: enabling reassembly into a meaningful unit of content split across multiple [=EPUB content documents=] (e.g., an index split across multiple documents), identifying resources for specialized purposes (e.g., preview content), or collecting together resources that present additional information about the [=EPUB publication=].

The role of each collection element MUST be identified in its role attribute, whose value MUST be one or more NMTOKENs [[xmlschema-2]] and/or [=absolute-URL-with-fragment strings=] [[url]].

The requirements for authoring specialized collections are defined by their respective specifications.

Introduction

The package document legacy features are retained from EPUB 2 only to allow the authoring of content that can function, to some degree, in [=reading systems=] that only support EPUB 2 publications.

These features were added primarily to address the overlap period as EPUB 3 reading systems were developed, as there was still a high probability at that time that users would be opening EPUB 3 publications on EPUB 2 reading systems.

As reading systems that only handle EPUB 2 publications are now rare, consider how likely it is that EPUB publications will still be opened on these types of older devices before making the effort to add these legacy features.

Support

[=EPUB publications=] MAY include the legacy features defined in this section for compatibility purposes with EPUB 2 reading systems.

EPUB 3 reading systems will not use these features when presenting publications to users.

The meta element

The meta element [[opf-201]] provides a means of including generic metadata for EPUB 2 [=reading systems=].

Refer to the meta element definition in [[opf-201]] for more information.

The guide element

The guide element [[opf-201]] provides machine-processable navigation to key structures in EPUB 2 [=reading systems=].

Refer to the guide element definition in [[opf-201]] for more information.

NCX

The NCX [[opf-201]] provides a table of contents for EPUB 2 [=reading systems=].

Refer to the NCX definition in [[opf-201]] for more information.

HTML requirements

An HTML content document:

• MUST conform to the conformance criteria for all document constructs defined by [[html]] unless explicitly overridden in .

• MAY include extensions to the [[html]] grammar as defined in , and MUST conform to all content conformance constraints defined therein.

• MUST either:

  • conform to the HTML syntax [[html]] when defined in the [=epub manifest|manifest=] as having the media type text/html; or
  • conform to the XML syntax [[html]] when defined in the [=epub manifest|manifest=] as having the media type application/xhtml+xml.

Unless specified otherwise, HTML content documents inherit all definitions of semantics, structure, and processing behaviors from the [[html]] specification.

HTML extensions

This section defines EPUB 3 [=XHTML content document=] extensions to the underlying [[html]] document model.

HTML deviations and constraints

This section defines deviations from, and constraints on, the underlying [[html]] document model applicable to EPUB 3 [=XHTML content documents=].

SVG requirements

An [=SVG content document=] MUST be a conforming SVG stand-alone file [[svg]] and conform to all content conformance constraints expressed in .

Restrictions on SVG

This specification restricts the content model of [=SVG content documents=] and SVG embedded by inclusion in XHTML content documents as follows:

• The [[svg]] foreignObject element:

  • MUST contain either [[html]] [=flow content=] or exactly one [[html]] body element.

    In the case of SVGs embedded by inclusion, a body element is not permitted per the restrictions on SVG defined in [[html]].

  • MUST contain a valid document fragment that conforms to the XHTML content document model defined in .

• If the [[svg]] [^title^] element contains marked-up text, the markup MUST contain only elements declared in the HTML namespace [[infra]].

  Although the [[svg]] title element allows markup elements, support for this feature is limited. The use of text-only titles is advised for maximum interoperability.

• When specified, the [^/epub:type^] attribute MUST only be included on [=renderable elements=] [[svg]].

  The SVG content model allows authors to include namespaced attributes, so this specification does not need to allow the [^/epub:type^] attribute or vocabulary association mechanisms.

  One key difference between SVGs embedded by reference and by inclusion, however, is that SVGs embedded by inclusion cannot have an epub:prefix attribute on their root [^svg^] element [[svg]]. For more information, refer to .

Cascading Style Sheets (CSS)

Scripting

The toc nav element

The primary navigational hierarchy of an [=EPUB publication=] is defined in a [^nav^] element [[html]] whose [^/epub:type^] attribute set to the value "toc" [[epub-ssv-11]] (i.e., the toc nav element). This element conceptually corresponds to a table of contents in a printed work — it provides navigation to the major structural sections of the publication.

The references in the toc nav element SHOULD be ordered such that they reflect both:

• the order of the referenced EPUB content documents in the [=EPUB spine | spine=]; and

• the order of the targeted elements within their respective [=EPUB content documents=].

The page-list nav element

The page list provides navigation to static page boundaries in the content. These boundaries either correspond to a statically paginated source such as print or are exclusively for the [=EPUB publication=].

The page list is defined in a [^nav^] element [[html]] whose [^/epub:type^] attribute is set to the value "page-list" [[epub-ssv-11]] (i.e., the page-list nav element).

The page-list nav element is OPTIONAL in [=EPUB navigation documents=] and MUST NOT occur more than once.

The page-list nav element SHOULD contain only a single ol descendant (i.e., no nested sublists).

The destinations of the page-list references MAY be identified in their respective [=EPUB content documents=] using the pagebreak term [[epub-ssv-11]].

The landmarks nav element

Landmarks identify fundamental structural components of the content to enable [=reading systems=] to provide the user efficient access to them (e.g., through a dedicated button in the user interface).

Landmarks are defined in a [^nav^] element [[html]] whose [^/epub:type^] attribute is set to the value "landmarks" [[epub-ssv-11]] (i.e., the landmarks nav element).

The landmarks nav element is OPTIONAL in [=EPUB navigation documents=] and MUST NOT occur more than once.

The landmarks nav element SHOULD contain only a single ol descendant (i.e., no nested sublists).

The [^/epub:type^] attribute is REQUIRED on a element descendants of the landmarks nav element. The structural semantics of each link target within the landmarks nav element is determined by the value of this attribute.

The landmarks nav MUST NOT include multiple entries with the same epub:type value that reference the same resource, or fragment thereof.

It is advised to limit the number of items defined in the landmarks nav to only items that a reading system is likely to use in its user interface. The element is not meant to repeat the table of contents.

It is advised to include the following landmarks when available:

• bodymatter [[?epub-ssv-11]] — Reading systems often use this landmark to automatically jump users past the front matter when they begin reading.
• toc [[?epub-ssv-11]] — If the table of contents is available in the spine, reading systems can use this landmark to take users to the document containing it.

Other possibilities for inclusion in the landmarks nav are key reference sections such as indexes and glossaries.

Although the landmarks nav is intended for reading system use, it is still advised to ensure that the labels for the landmarks nav are human readable. Reading systems might expose the links directly to users.

Other nav elements

[=EPUB navigation documents=] MAY contain one or more nav elements in addition to the toc, page-list, and landmarks nav elements defined in the preceding sections. If these nav elements are intended for [=reading system=] processing, they MUST have an [^/epub:type^] attribute and are subject to the content model restrictions defined in .

This specification imposes no restrictions on the semantics of any additional nav elements: they MAY represent navigational semantics for any information domain, and they MAY contain link targets with homogeneous or heterogeneous semantics.

Fixed-layout package settings

The rendition:flow property

The rendition:flow property specifies the preference for how [=reading systems=] handle content overflow.

When the rendition:flow property is specified on a meta element, it indicates the preference for overflow content handling (i.e., for all [=EPUB spine | spine=] items). Either dynamic pagination or scrolling MAY be specified. For scrolled content, it is also possible to specify whether consecutive [=EPUB content documents=] are to be rendered as a continuous scrolling view or whether each is to be rendered separately (i.e., with a dynamic page break between each).

One of the following values MUST be used with the rendition:flow property:

paginated

Dynamically paginate all overflow content.

scrolled-continuous

Render all EPUB content documents such that overflow content is scrollable, and the [=EPUB publication=] is presented as one continuous scroll from spine item to spine item (except where locally overridden).

Resources SHOULD NOT have different block flow directions as it makes continuous scrolled rendition in EPUB reading systems problematic.

scrolled-doc

Render all EPUB content documents such that overflow content is scrollable, and each spine item is presented as a separate scrollable document.

auto

Render overflow content using the reading system default method or a user preference, whichever is applicable. Default value.

Note that when two reflowable EPUB content documents occur sequentially in the spine, the default rendering for their [[!html]] body elements is consistent with the page-break-before property [[!csssnapshot]] having been set to always. In addition to using the rendition:flow property, this behavior MAY be overridden through an appropriate style sheet declaration if the reading system supports such overrides.

The rendition:flow property MUST NOT be declared more than once. In addition, it MUST NOT be declared using the refines attribute. Refer to for setting the property for individual EPUB content documents.

The rendition:align-x-center property

The rendition:align-x-center property specifies to center the given [=EPUB spine | spine=] horizontally in the [=viewport=] or spread.

The property MUST NOT be set globally for all [=EPUB content documents=] (i.e., in a [^meta^] element without a refines attribute). It is only available as a spine override for individual EPUB content documents via the [^itemref^] element's properties attribute.

Media overlay document requirements

A [=media overlay document=]:

• MUST be valid to the media overlays schema as defined in and conform to all content conformance constraints expressed in .

• MAY refer to more than one [=EPUB content document=], but more than one media overlay document MUST NOT reference the same EPUB content document.

Media overlay document definition

All elements [[xml]] defined in this section are in the https://www.w3.org/ns/SMIL namespace [[xml-names]] unless otherwise specified.

Relationship to the EPUB content document

Structural semantics in overlays

To express structural semantics in [=media overlay documents=], the [^/epub:type^] attribute MAY be specified on [^par^], [^seq^], and [^body^] elements.

The epub:type attribute facilitates [=reading system=] behavior appropriate for the semantic type(s) indicated. Examples of these behaviors are skippability and escapability and table reading mode [[?epub-rs-34]].

[=Media overlay documents=] MAY use the applicable vocabulary association mechanisms for the epub:type attribute to define additional semantics.

Associating style information

Visual rendering information for the currently playing [=EPUB content document=] element MAY be expressed in a CSS Style Sheet using author-defined classes.

When used, the class names MUST be declared in the [=package document=] using the active-class and playback-active-class properties.

Exactly one CSS class name MUST be defined in each property they define. Each property MUST define a valid CSS class name not including any selectors [[css2]]. This specification does not reserve names for use with these properties.

Any CSS properties MAY be defined for the specified CSS classes. Each EPUB content document with an associated [=media overlay document=] has to include a CSS stylesheet (either embedded or linked) containing the class definitions. In the absence of such definitions [=reading systems=] might provide their own styling, or no styling at all.

The active-class and playback-active-class properties MUST NOT be used in conjunction with a refines attribute as they always apply to the entire [=EPUB publication=].

Media overlays packaging

Skippability

While reading, users might want to turn on or off certain features of the content, such as footnotes, page numbers, or other types of secondary content. This feature is called skippability. [=Reading systems=] use the semantic information provided by media overlay elements' epub:type attribute to determine when to offer users the option of skippable features.

The following semantics MAY be used to enable skippability:

• footnote [[epub-ssv-11]]

• endnote [[epub-ssv-11]]

• pagebreak [[epub-ssv-11]]

This list is non-exhaustive, however. It represents terms from the Structural Semantics Vocabulary [[?epub-ssv-11]] for which reading systems are most likely to offer the option of skippability.

Escapability

Escapable items are nested structures, such as tables and lists, that users might wish to skip over, continuing to read from the point immediately after the nested structure. The escapability feature differs from the skippability feature in that it does not enable or disable entire types of items, but provides an exit from them (e.g., a user can listen to some of the content before choosing to escape).

The following semantics MAY be used to enable escapability:

• table [[epub-ssv-11]]

• list [[epub-ssv-11]]

• figure [[epub-ssv-11]]

• aside [[epub-ssv-11]]

This list is non-exhaustive list, however. It represents terms from the Structural Semantics Vocabulary [[?epub-ssv-11]] for which [=reading systems=] are most likely to offer the option of escapability.