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 the full fallback chain for that item. This chain also represents the [=EPUB creator | EPUB creator's=] preferred fallback order.

There are two cases for manifest fallbacks:

Spine fallbacks

EPUB creators MUST specify a fallback chain for a [=foreign content document=] to ensure that reading systems can always render the [=EPUB spine | spine=] item. In this case, the chain MUST contain at least one [=EPUB content document=].

EPUB creators MAY provide fallbacks for EPUB content documents (e.g., to provide a fallback for scripted content).

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

Content fallbacks

The original purpose for content fallbacks was to specify fallback images for the [[html]] [^img^] element. As HTML now has intrinsic fallback mechanism for images, the use of content fallbacks is strongly discouraged. EPUB creators should always use the intrinsic fallback capabilities of [[html]] and [[svg]] to provide fallback content.

EPUB creators MUST provide a content fallback for [=foreign resources=] when the elements that reference them do not have intrinsic fallback capabilities. In this case, the fallback chain MUST contain at least one [=core media type resource=].

EPUB creators MAY also provide manifest fallbacks for core media type resources (e.g., 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=].

[=EPUB creators=] MAY locate all other files within the OCF abstract container in any location descendant from the root directory, provided they are not within the META-INF directory. EPUB creators MUST NOT reference files in the META-INF directory from an [=EPUB publication=].

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 may 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]] also includes a list of deprecated characters. EPUB creators are advised to avoid these characters, as well, 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=]. It is implementation-specific, but [=EPUB creators=] MUST assume it has 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 must be 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 may 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 must be 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, [=EPUB creators=] MUST set the version needed to extract fields to the values 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, EPUB creators MUST set the compression method field to the values 0 or 8.

OCF ZIP container media type identification

[=EPUB creators=] MUST include the mimetype file as 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 white space.
• The mimetype file MUST NOT begin with the Unicode byte order mark U+FEFF.
• EPUB creators MUST NOT compress or encrypt the mimetype file.
• EPUB creators MUST NOT include an extra field in its ZIP header.

Obfuscation key

[=EPUB creators=] MUST derive the key used in the obfuscation algorithm from the [=unique identifier=].

All white space 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.

EPUB creators MUST generate a SHA-1 digest of the UTF-8 representation of the resulting string as specified by the Secure Hash Standard [[fips-180-4]]. They can then use this digest 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.

[=EPUB creators=] MUST obfuscate fonts 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 ).

[=EPUB creators=] MUST specify an EncryptedData element 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.

EPUB creators MUST list the path to the obfuscated font in the CipherReference child of the CipherData element. 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, EPUB creators MUST NOT provide the obfuscation key 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 EPUB creators omit the attribute or use an invalid value.

Allowed on: [^collection^], [^dc:contributor^], dc:coverage, [^dc:creator^], dc:description, dc:publisher, dc:relation, dc:rights, [^dc:subject^], [^dc:title^], [^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^], [^dc:contributor^], dc:coverage, [^dc:creator^], [^dc:date^], dc:description, dc:format, [^dc:identifier^], [^dc:language^], dc:publisher, dc:relation, dc:rights, dc:source, [^dc:subject^], [^dc:title^], [^dc:type^], [^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. [=EPUB creators=] MUST use as the value a [=path-relative-scheme-less-URL string=], optionally followed by U+0023 (#) and a [=URL-fragment string=] that references the resource or element they are describing.

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^], [^dc:contributor^], dc:coverage, [^dc:creator^], dc:description, dc:publisher, dc:relation, dc:rights, [^dc:subject^], [^dc:title^], [^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 [=EPUB creators=] need to provide more detailed information, they can associate metadata records (e.g., that conform to an international standard such as [[onix]] or are created for custom purposes) 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 EPUB creators MAY use this mechanism for any metadata purposes, they will typically use it to include rendering 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 must 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 required elements

<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>

Dublin Core optional elements

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 [=EPUB creators=] can define 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.

EPUB creators MAY use subexpressions 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.

EPUB creators MAY add terms from other vocabularies as defined in .

The scheme attribute identifies the system or scheme the EPUB creator obtained the element's [=value=] 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 [[xmlschema-2]] dateTime conformant date of the form: CCYY-MM-DDThh:mm:ssZ

[=EPUB creators=] MUST express the last modification date in Coordinated Universal Time (UTC) and MUST terminate it with the "Z" (Zulu) time zone indicator.

EPUB creators should update the last modified date whenever they make changes to the [=EPUB publication=].

EPUB creators MAY specify additional modified properties 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 [=EPUB creators=] MUST NOT list them in the manifest.

EPUB creators MAY locate linked resources within the [=EPUB container=] or externally, but should consider that [=reading systems=] are not required to retrieve resources outside the EPUB container.

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

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, EPUB creators MAY specify a semantic identifier in the properties attribute.

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

EPUB creators MAY add relationships and properties from other vocabularies as defined in .

EPUB creators MAY provide one or more linked metadata records.

In addition to full records, EPUB creators MAY also use the link element 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]]. [=EPUB creators=] MUST ensure each URL is 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=], EPUB creators MUST use the media type designated in .

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 bindings element (deprecated)

The bindings element defines a set of custom handlers for media types not supported by this specification.

Use of the element is deprecated.

Refer to the bindings element definition in [[epubpublications-301]] 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=].

[=EPUB creators=] MUST list in the spine all EPUB and foreign content documents that are hyperlinked to from publication resources 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., EPUB creators must list all EPUB and foreign content documents hyperlinked to from hyperlinked documents, and so on.).

EPUB creators also MUST list in the spine all EPUB and foreign content documents hyperlinked to from the [=EPUB navigation document=], regardless of whether EPUB creators include the EPUB navigation document 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 EPUB creators specify the default value, they are expressing no preference 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 may 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=] must 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 should 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, however; it is only a hint to the purpose. Reading systems may present non-linear content where it occurs in the spine, for example, or may 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.

EPUB creators MUST provide a means of accessing all non-linear content (e.g., hyperlinks in the content or from the EPUB navigation document).

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

EPUB creators MAY add terms from other vocabularies 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 [=EPUB creators=] to assemble resources 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=].

EPUB creators MUST identify the role of each collection element 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.

Defining collection types (deprecated)

The creation of new collection element roles is now deprecated.

Refer to the collection element definition in [[epubpackages-32]] for more information about the creation of specialized collections, including the requirements and restrictions on their use.

Introduction

The package document legacy features are retained from EPUB 2 only to allow [=EPUB creators=] to author 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, EPUB creators should consider the likelihood of their publications still being opened on these types of older devices before making the effort to add these legacy features.

Support

[=EPUB creators=] 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.

XHTML requirements

An [=XHTML content document=]:

• MUST be an [[html]] document that conforms to the XML syntax.

• 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.

Unless specified otherwise, XHTML 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. [=EPUB creators=] are advised to use text-only titles for maximum interoperability.

• Proposed Correction 3

  This correction adds the restriction on where the epub:type attribute is allowed (refer to proposed correction 2 for its former placement). Moving the restriction into this section also makes it applicable to SVGs embedded by inclusion in HTML documents, a requirement that was not clearly established when the restriction was in the preceding section. For more information, refer to issue 2555.

  This correction also addresses the list of elements the [^/epub:type^] attribute is allowed on. The current list (see proposed correction 2) does not allow the attribute on the SVG [^a^] element. The text is corrected to use the [[svg2]] definition of a renderable element to avoid the problem of missing elements when selecting more granular element classes. For more information, refer to issue 2556.

  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 toc nav element defines the primary navigational hierarchy. It conceptually corresponds to a table of contents in a printed work (i.e., it provides navigation to the major structural sections of the publication).

[=EPUB creators=] SHOULD order the references in the toc nav element 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 element provides navigation to static page boundaries in the content. These boundaries may correspond to a statically paginated source such as print or may be defined exclusively for the [=EPUB publication=].

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).

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

The landmarks nav element

The landmarks nav element identifies fundamental structural components in the content to enable [=reading systems=] to provide the user efficient access to them (e.g., through a dedicated button in the user interface).

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.

[=EPUB creators=] should limit the number of items they define 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.

The following landmarks are recommended to include 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 may 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, EPUB creators should still ensure that the labels for the landmarks nav are human readable. Reading systems may 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 [=EPUB creator=] preference for how [=reading systems=] should handle content overflow.

When the rendition:flow property is specified on a meta element, it indicates the EPUB creator's global preference for overflow content handling (i.e., for all [=EPUB spine | spine=] items). EPUB creators MAY indicate a preference for dynamic pagination or scrolling. 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).

EPUB creators MUST use one of the following values 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).

Note that EPUB creators SHOULD NOT create publications in which different resources have different block flow directions, as continuous scrolled rendition in EPUB reading systems would be 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.

Note that if this value is applied to an EPUB with a pre-paginated layout, it will render the same as if paginated was applied.

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, EPUB creators MAY override this behavior through an appropriate style sheet declaration, if the reading system supports such overrides.

EPUB creators MUST NOT declare the rendition:flow property more than once.

They also MUST NOT declare the property using the refines attribute. Refer to for setting the property for individual EPUB content documents.

Image description

Three rectangles linked left-to-middle and middle-to-right with respective arrows, representing three spine items or pages in an EPUB document. Each page is one piece of a comics. Each rectangle fills the screen of the schematic view of a tablet.

Image description

A single, column-like strip (i.e. a rectangle without a bottom edge) with multiple comic pages flowing down the strip. The content is segmented by the page boundaries, but there are no gaps between the pages. The top part of the strip is enclosed in a schematic view of a tablet.

Image description

Three rectangles linked left-to-middle and middle-to-right with respective arrows, representing three pages in an EPUB document. Each page is one piece of a comics. Each rectangle fills the screen of the schematic view of a tablet.

The rendition:align-x-center property

The rendition:align-x-center property specifies that the given [=EPUB spine | spine=] item should be centered 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=], [=EPUB creators=] MAY specify the [^/epub:type^] attribute 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-33]].

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

Associating style information

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

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

EPUB creators MUST define exactly one CSS class name 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.

EPUB creators MAY define any CSS properties for the specified CSS classes but must ensure that each EPUB content document with an associated [=media overlay document=] includes 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.

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

Media overlays packaging

Skippability

While reading, users may 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.

[=EPUB creators=] MAY use the following semantics 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).

[=EPUB creators=] MAY use the following semantics 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.