EPUB Reading Systems 3.3

EPUB® 3 defines a distribution and interchange format for digital publications and documents. The EPUB format provides a means of representing, packaging, and encoding structured and semantically enhanced web content — including HTML, CSS, SVG and other resources — for distribution in a single-file container.

This specification defines the conformance requirements for EPUB 3 reading systems — the user agents that render EPUB publications.

Introduction

Overview

The EPUB 3 standard is separated into two distinct concerns: the authoring of [=EPUB publications=] is defined in the core specification [[epub-33]], while this specification details the rendering requirements for them in [=EPUB reading system=].

An EPUB reading system can take many forms. It might have a visual display area for rendering the content to users, for example, or it might only provide audio playback of the content. Therefore, there is no single set of rules that applies to all reading systems. Rather, this specification breaks down the rendering requirements based on a reading system's capabilities and the features it supports.

Moreover, this specification allows for a great deal of flexibility for developers to create unique user interfaces, and requirements for things like metadata processing are intentionally minimal to allow for such flexibility.

So, although this specification identifies the formal requirements for reading systems, it is not possible to understand this document in isolation. Developers should also familiarize themselves with the full content structure of an EPUB publication in order to understand the complete range of information that is available.

A conforming reading system is not necessarily a single dedicated program or device but might exist as a distributed system.

Terminology

This specification uses terminology defined in EPUB 3.3 [[epub-33]].

It also defines the following term:

content display area

The area within the [=viewport=] dedicated to the display of EPUB content documents. The content display area excludes any borders, margins, headers, footers, or other decoration a [=EPUB reading system=] might inject into the viewport.

In the case of [=synthetic spreads=], the viewport contains two content display areas.

Only the first instance of a term in a section links to its definition.

All algorithm explanations are non-normative.

Relationship to other specifications

Relationship to HTML

The [[html]] standard is continuously evolving — there are no longer versioned releases of it. That standard, in turn, references various technologies that continue to evolve, such as MathML, SVG, CSS, and JavaScript.

[=Reading system=] developers must keep track of the changes to HTML, and the technologies it references, to ensure they keep their systems up to date.

This specification does not require EPUB reading systems to support scripting, form submission, or the HTML DOM [[dom]]. Reading systems conformant with this specification are only expected to be able to process a conforming [=EPUB content document=]. As support for scripting and form submission is not compulsory, a conformant reading system might not be a fully conformant HTML user agent.

Relationship to SVG

This specification does not reference a specific version of [[svg]], but instead uses an undated reference. Whenever there is any ambiguity in this reference, the latest recommended specification is the authoritative reference.

This approach ensures that EPUB will always keep pace with changes to the SVG standard. [=Reading system=] developers must keep track of changes to the SVG standard to ensure that they keep their systems up to date.

Publication resource processing

[=Reading systems=] MUST process publication resources [[epub-33]].

Core Media types

If a reading system has a [=viewport=], it MUST support the image core media type resources [[epub-33]].

If it has the capability to render prerecorded audio, it MUST support the audio core media type resources [[epub-33]].

It is recommended that reading systems support at least one of the H.264 [[h264]] and VP8 [[rfc6386]] video codecs, but this is not a conformance requirement — a reading system may support any video codec, or none at all. Reading system developers should take into consideration factors such as breadth of adoption, playback quality, and technology royalties when deciding which video formats to support.

Foreign resources

Reading systems MAY support an arbitrary set of [=foreign resource=] types, and if a foreign resource is not supported, MUST process fallbacks as defined in foreign resources [[epub-33]].

Resource locations

Reading systems SHOULD support [=remote resources=], as defined in Resource locations [[epub-33]].

To limit the risk of network attacks, reading systems SHOULD only load remote resources referenced via the https URI scheme [[rfc9110]].

Data URLs

Reading systems MUST prevent data URLs [[rfc2397]] from opening in [=top-level browsing contexts=] [[html]], except when initiated through a reading system affordance such as a context menu. If a reading system does not use a top-level browsing context for [=top-level content documents=], for example if the top-level content document is an SVG, it MUST also prevent data URLs from opening as though they are top-level content documents.

File URLs

Reading Systems MUST prevent access to resources referenced via file URLs [[rfc8089]].

XML processing

A [= reading system =] MUST use a non-validating XML processor [[xml]] that:

does not read external DTD subsets [[xml]];
conforms to [[xml-names]].

Internationalization

As part of processing [=publication resources=], a reading system is required to process the attributes to set the language and the base directions in [=XHTML content documents=] or [=SVG content documents=], as well as the xml:lang attribute for all XML documents (e.g., the [=package document=] and [=media overlay documents=]).

Furthermore, a reading system MUST also process the dir attribute [[epub-33]] for the [=package document=], where the base direction specified by dir applies to the element where it is specified, and to all elements in its content unless overridden with another instance of dir. (See also for further details.)

In the absence of this information in a [=publication resource=], reading systems MUST NOT assume either the language or the base direction of that resource from information expressed in the package document (i.e., in xml:lang and dir attributes, in hreflang attributes on [^link^] elements, or from [^dc:language^] elements [[epub-33]]). Refer to a resource's formal specification for more information about to handle the absence of explicit language or direction information.

Network access

Reading systems MAY support network access to retrieve remote resources and to allow [=scripted content documents=] to communicate with web-hosted APIs and retrieve resources.

Providing network access, however, increases both the security risks to the reading systems and the security and privacy risks to users. These risks are often unique to reading systems and the platforms they run on — the browser cores that most reading systems are built on do not offer the same security and privacy controls as web browsers themselves. Consequently, developers need to use extra caution when allowing network access, and more thoroughly test that their reading systems are not vulnerable to attacks. More information about these risks is provided in .

If reading system developers allow network access, it is RECOMMENDED both that they:

notify users when network activity occurs; and
let users block access to the network (e.g., disable network access for the reading system globally or for a particular EPUB publication).

External links

When a link has an http or https scheme [[url]], reading systems:

SHOULD obtain the user's consent before opening the link.
SHOULD open the link in a new browser instance to ensure that the browser's security and privacy controls are available to users.

External links are not only found in [=EPUB content documents=]. A reading system might provide access to external linked records [[epub-33]] in the package document metadata, for example.

For more information about security and privacy issues with external links, see .

Open Container Format (OCF) processing

[=Reading systems=] MUST process the EPUB container [[epub-33]].

An application that processes EPUB containers does not have to be a full-fledged reading system (e.g., an application might only extract the content of a container or check the validity of the packaged content). In these cases, developers of such applications can ignore the rendering requirements for reading systems defined in this section.

OCF abstract container

URL of the root directory

Reading systems MUST assign a URL [[url]] to the [=root directory=] of the [=OCF abstract container=]. This URL is called the [=container root URL=]. It is implementation specific, but the implementation MUST have the following properties:

The result of parsing [[url]] "/" with the container root URL as base is the container root URL.
The result of parsing [[url]] ".." with the container root URL as base is the container root URL.
The origin [[url]] of the [=container root URL=] is unique for each user-specific instance of an [=EPUB publication=] in a reading system.

The unicity of the origin [[html]] per each user-specific instance of an EPUB publication in a reading system means that if two different users acquire a copy of the same EPUB publication, the origins will be different for the two users on those copies even if the same reading system is used.

The properties of the [=container root URL=] are such that a conforming reading system will parse any relative URL string to a [=content URL=]. In other words, relative links do not "leak" outside the container content, which is an important feature for security.

In practice, the container root URL behaves similarly to a URL defined as follows:

URL component	Values
scheme	`http` or `https`
host	`localhost`
port	a dynamic port uniquely assigned to the EPUB instance

for example:

Container File	File Path	URL
Root directory	`empty string`	`http://localhost:49152/`
Package document	`EPUB/package.opf`	`http://localhost:49152/EPUB/package.opf`
EPUB content document	`HTML/file name.xhtml`	`http://localhost:49152/HTML/file%20name.xhtml`

URL string (found for example in the package document)	content URL
`../HTML/file%20name.xhtml`	`http://localhost:49152/HTML/file%20name.xhtml`
`/Media/img.png`	`http://localhost:49152/Media/img.png`
`../../../Media/img.png`	`http://localhost:49152/Media/img.png`

Note that the last two links are disallowed in an EPUB publications to ensure better interoperability with non-conforming or legacy reading systems and toolchains.

Some language specifications reference Requests For Comments that preceded [[url]], in which case the earlier RFC applies for content in that particular language.

Unlike most language specifications, reading systems must use the [=container root URL=] as the base URL [[url]] for all files within the META-INF directory. See also the section on Parsing URLs in the META-INF directory in [[!epub-33]].

File names

Although [=EPUB creators=] are required to follow various file name and file path restrictions [[epub-33]] for maximum interoperability, reading systems SHOULD attempt to process file names and paths that do not adhere to these requirements. Invalid file names and paths may only be problematic on some operating systems.

This specification does not specify how a reading system that is unable to represent OCF file names and paths would handle this incompatibility.

`META-INF` directory

Container file (container.xml)

A reading system MUST, by default, use the [=package document=] referenced the from first [^rootfile^] element [[epub-33]] to render the [=EPUB publication=]. If the reading system recognizes a means of selecting from the other available options, it MAY choose a more appropriate package document.

Metadata file (metadata.xml)

Reading systems SHOULD ignore metadata.xml files [[epub-33]] with unrecognized root elements.

Manifest file (manifest.xml)

Reading systems MUST NOT use ancillary manifest information contained in the ZIP archive or in the manifest.xml file [[epub-33]] for processing an [=EPUB publication=].

Signature file (signatures.xml)

Before computing the digest used to validate the signature in the signatures.xml file [[epub-33]], reading systems MUST decrypt any data encrypted after signing — data encrypted before signing MUST NOT be decrypted.

Refer to Decryption Transform for XML Signature [[xmlenc-decrypt]] for more information about identifying data encrypted after signing.

Other files

Reading systems MUST NOT fail when encountering configuration files in the META-INF directory not listed in Reserved files [[epub-33]].

OCF ZIP container

A reading system:

MUST treat any [=OCF ZIP container=] that splits the content into segments [[zip]] as in error.
MUST treat any OCF ZIP container that uses compression techniques other than Deflate [[rfc1951]] as in error.
MUST support the ZIP64 extensions defined as "Version 1" [[zip]].
MUST treat an OCF ZIP container that uses [[zip]] encryption features as in error.
MAY generate a physical directory for the [=root directory=] of the [=OCF abstract container=] if it unzips the contents.
does not have to preserve information from an OCF ZIP container through load and save operations outside the context of the OCF abstract container. In particular, a reading system does not have to preserve CRC values, comment fields or fields that hold file system information corresponding to a particular operating system (e.g., External file attributes and Extra field).

With respect to specific fields in the OCF ZIP container archive, the reading system:

MUST treat version needed to extract field values other than 10, 20 or 45 in the local file header table [[zip]] as being in error.
MUST treat compression method field values other than 0 or 8 in the local file header table [[zip]] as being in error.
MUST treat OCF ZIP containers with an Archive decryption header or an Archive extra data record [[zip]] as being in error.

Font obfuscation

Reading systems SHOULD support deobfuscation of fonts as defined in Font obfuscation [[epub-33]].

To restore the original data, reading systems should simply reverse the process: the source file becomes the obfuscated data, and the destination file contains the raw data.

EPUB 3 allowed font obfuscation prior to EPUB 3.0.1, but did not specify the order of obfuscation and compression. As a result, reading systems might encounter invalid fonts after decompression and deobfuscation. In such instances, deobfuscating the data before inflating it may return a valid font. Reading systems do not have to support this method of retrieval, but developers should consider it when supporting EPUB 3 content generally.

Package document processing

[=Reading systems=] MUST process the package document [[epub-33]].

Base direction

If the dir attribute [[epub-33]] is set and indicates a base direction of ltr or rtl, reading systems MUST override the bidi algorithm per the higher-level protocols defined in [[bidi]], setting the paragraph embedding level to 0 if the base direction is ltr, or 1 if the base direction is rtl.

Otherwise the base direction is auto, in which case reading systems MUST determine the text's direction by applying the Unicode Bidi Algorithm, beginning with Rule P2 of [[bidi]].

Although setting the directionality of package document metadata is marked as under-implemented in [[epub-33]], reading system with an international audience, or that claim support for international content, are strongly advised to implement this feature when exposing that metadata to users. Ignoring the directionality of text can cause readability issues.

The under-implemented label will be removed from [[epub-33]] when the necessary baseline of support in reading systems has been achieved.

Unique identifier

Reading systems SHOULD NOT depend on the [=unique identifier=] being unique to one and only one [=EPUB publication=]. Determining whether two EPUB publications with the same unique identifier represent different versions of the same publication, or different publications, may require inspecting other metadata, such as their last modification dates, titles, and authors.

Metadata

Whitespace

Reading systems MUST [=strip and collapse ASCII whitespace=] [[infra]] from Dublin Core [[dcterms]] and [^meta^] element values [[epub-33]] before processing.

The dc:identifier element

To determine whether the value of a [^dc:identifier^] element [[epub-33]] conforms to an established system or has been granted by an issuing authority, reading systems SHOULD check for an identifier-type property [[epub-33]].

The dc:title element

Reading systems MUST recognize the first [^dc:title^] element [[epub-33]] in document order as the main title of the [=EPUB publication=] and present it to users before other title elements.

This specification does not define how to process additional dc:title elements.

The dc:language element

The language(s) of the EPUB publication specified in [^dc:language^] elements are informational. Some uses of this information include:

exposing it to the user through the reading system user interface
using it to enhance functionality in a bookshelf (e.g., sorting by language)
using it to optimize the reading interface (e.g., to preload text-to-speech languages)

See for more details on how to determine the language of a [=publication resource=].

The dc:creator element

When determining display priority, reading systems MUST use the document order of [^dc:creator^] elements [[epub-33]] in the metadata section, where the first creator element encountered is the primary creator. If a reading system exposes creator metadata to the user, it SHOULD include all the creators listed in the metadata section whenever possible (e.g., when not constrained by display considerations).

The meta element

Reading systems SHOULD ignore all [^meta^] elements whose property attributes [[epub-33]] define expressions they do not recognize. A reading system MUST NOT fail when encountering unknown expressions.

If a reading system does not recognize the scheme attribute [[epub-33]] value, it SHOULD treat the value of the element as a string.

The link element

Retrieval and support of [=linked resources=] is OPTIONAL.

The language identified in an hreflang [[EPUB-33]] attribute is purely advisory. The language information expressed in the resource determines its language for processing and rendering purposes, as defined in the internationalization requirements.

Manifest

Reading systems MUST ignore values of the properties attribute [[epub-33]] they do not recognize.

Reading systems SHOULD NOT use [=linked resources=] in the rendering of an [=EPUB publication=] due to the inherent limitations and risks involved (e.g., lack of information about the resource and how to process it, security risks from remotely-hosted sources, lack of fallbacks, etc.).

A reading system that does not support the MIME media type [[rfc2046]] of a given [=publication resource=] MUST traverse the manifest fallback chain [[epub-33]] until it identifies a supported publication resource to use in place of the unsupported resource. If the reading system supports multiple publication resources in the fallback chain, it MAY select the resource to use based on the resource's properties attribute [[epub-33]] values, otherwise it SHOULD honor the [=EPUB creator|EPUB creator's=] preferred fallback order. If a reading system does not support any resource in the fallback chain, it MUST alert the user that it could not display the content.

When manifest fallbacks [[epub-33]] are provided for [=top-level content documents=], reading systems MAY choose from the available options to find the optimal version to render in a given context (e.g., by inspecting the properties attribute for each).

A reading system MUST terminate the fallback chain at the first reference to a manifest item it has already encountered.

Spine

Reading systems MUST provide a means of rendering an [=EPUB publication=] in the order defined in the [^spine^] element [[epub-33]], which includes:

recognizing the first primary (linear) itemref [[epub-33]] as the beginning of the default reading order; and,
rendering successive primary items in the order given in the spine.

When a user traverses the default reading order defined in the spine element, a reading system MAY automatically skip non-linear itemref elements [[epub-33]]. When a user activates a hyperlink to a non-linear resource, however, reading systems MUST render the referenced resource or a designated fallback. Reading systems MAY also provide the option for users to skip non-linear content by default or not.

If the [=EPUB creator=] has not specified the page-progression-direction attribute [[epub-33]], the reading system MUST assume the value of default. When page-progression-direction value is default, the reading system can choose the rendering direction.

If the page-progression-direction attribute has a value other than default, the reading system MUST ignore any directionality computed from pre-paginated [=XHTML content documents=].

Reading systems MUST ignore all values expressed in spine itemref properties attributes [[EPUB-33]] that they do not recognize.

Reading systems MUST NOT skip spine references to duplicate manifest items [[EPUB-33]] when rendering the linear reading order. The reading system MUST treat these as distinct items for user interface (UI) purposes (for example, each occurrence could be independently bookmarked or annotated). When a reading system follows a hyperlink to a resource referenced multiple times in the spine, the reading system MUST navigate to the first occurrence of the document in the linear reading order.

Spine overrides

When a [=spine=] [^itemref^] element's properties attribute overrides a global rendering property [[epub-33]], reading systems MUST follow the requirements for the override's global value to display that spine item.

For example, a spine item that contains the layout-pre-paginated override [[epub-33]] is rendered following the requirements of the global pre-paginated value.

If more than one override for the same property is specified in a properties attribute, reading systems MUST use only the first value.

Collections

In the context of this specification, support for collections [[epub-33]] in reading systems is OPTIONAL. Reading systems MUST ignore collection elements that define unrecognized roles.

Legacy features

Reading systems MUST NOT support legacy features in content that conforms to this version of EPUB [[epub-33]].

EPUB content document processing

The definition of EPUB content documents [[epub-33]] includes various authoring restrictions to optimize the cross-compatibility of content (e.g., prohibiting CSS for setting language and direction [[?epub-33]]). Unless stated otherwise in this specification, reading systems MAY support these restricted features.

XHTML content documents

[=Reading systems=] MUST process XHTML content documents [[epub-33]].

Unless explicitly defined in this section as overridden, reading systems MUST process XHTML content documents using semantics defined by the [[html]] specification and honor any applicable user agent conformance constraints expressed therein.

HTML extensions

RDFa

Reading system support for the attribute processing model [[rdfa-core]] is OPTIONAL.

Content switching (deprecated)

Use of the switch element is deprecated [[epub-33]]. Refer to its definition in [[epubcontentdocs-301]] for implementation information.

The `epub:trigger` element (deprecated)

Use of the trigger element is deprecated [[epub-33]]. Refer to its definition in [[epubcontentdocs-301]] for implementation information.

Custom attributes

Reading systems MAY support custom attributes provided the attributes do not modify the requirements of this specification.

HTML deviations and constraints

Microdata

Reading system support for the attribute processing model is OPTIONAL, as is the conversion to JSON [[html]].

MathML

To support MathML [[mathml3]] embedded in [=XHTML content documents=], a reading system:

MUST be an input-compliant processor for Presentation MathML, as defined in the [[mathml3]] specification.
MUST, if it has a [=viewport=], support visual rendering of Presentation MathML.
MAY support rendering of Content MathML found in annotation-xml elements [[mathml3]].

Reading systems may choose to use third-party libraries such as MathJax to provide MathML rendering.

Embedded SVG

Reading systems MUST process SVG embedded in [=XHTML content documents=] as defined in .

Embedded SVG and CSS

For the purposes of styling SVG embedded in [=XHTML content documents=] by reference, reading systems MUST NOT apply CSS style rules of the containing document to the referenced SVG document.

For the purposes of styling SVG embedded in XHTML content documents by inclusion, reading systems MUST apply applicable CSS rules of the containing document to the included SVG elements.

SVG included by reference is processed as a separate document, and can include its own CSS style rules just like an [=SVG content document=] would. Note that this is consistent with situations where an [[html]] object element references an external [[html]] element.

Form submission

Reading system support for the submission of [[html]] [^form^] elements is OPTIONAL. A reading system might, for example, prevent form submissions by limiting access to networking.

SVG content documents

[=Reading systems=] MUST process SVG content documents [[epub-33]].

To process SVG content documents and SVG embedded in XHTML content documents, a reading system:

MUST process SVG content documents using semantics defined by the [[svg]] specification, and honor any applicable user agent conformance constraints expressed therein, unless explicitly defined by this specification as overridden.
MUST meet the conformance criteria defined in .
MUST, if it has a [=viewport=], support the visual rendering of SVG using CSS as defined in Styling [[svg]] and it SHOULD support all properties defined in the Property Index [[svg]]. In the case of embedded SVG, a reading system MUST also conform to the constraints defined in .

Cascading Style Sheets (CSS)

If a reading system has a [=viewport=], it MUST support the visual rendering of XHTML content documents via CSS [[epub-33]].

To support CSS, a reading system:

MUST support the official definition of CSS as described in the [[csssnapshot]].
SHOULD support all applicable modules in [[csssnapshot]] that have reached at least Candidate Recommendation status [[w3cprocess]] (and are widely implemented).
MUST support [[truetype]], [[opentype]], [[woff]], and [[woff2]] font resources referenced from @font-face rules [[css-fonts-4]].
SHOULD support all prefixed properties defined in CSS Style Sheets — Prefixed properties [[epub-33]].
SHOULD apply [=EPUB creator=] style sheets as written to [=EPUB content documents=].
SHOULD NOT override the EPUB creator's style sheets, but SHOULD do so in a way that preserves the Cascade when necessary: through a user agent style sheet, or [[html]] [^html-global/style^] attributes.
It MAY override parts of the EPUB creator's style sheet because of user interaction.

In addition to supporting CSS properties as defined above, a reading system's user agent style sheet SHOULD support the [[html]] suggested default rendering.

Reading system developers should implement CSS support at the level of major browsers and publicly document their user agent style sheets and how they interact with EPUB creator's style sheets.

Scripting

[=Reading systems=] SHOULD support scripting [[epub-33]].

Reading system support for scripting depends on its usage context:

Reading systems SHOULD support container-constrained scripting [[epub-33]] in reflowable [=EPUB content documents=].
Reading systems SHOULD support spine-level scripting [[epub-33]] in fixed-layout documents [[epub-33]].
Reading systems SHOULD support spine-level scripting in reflowable EPUB content documents that use the "scrolled-doc" or "scrolled-continuous" [[epub-33]] presentation modes defined by the rendition:flow property. Similarly, if it supports spine-level scripting in reflowable EPUB content documents, it MUST implement the "scrolled-doc" presentation mode and SHOULD implement the "scrolled-continuous" presentation mode.
Reading systems MAY support scripting in other contexts, but this specification does not address such scripting. As a result, the use of scripting in these contexts may not be consistent across reading systems.

If a reading system supports scripting:

It MAY render [=scripted content documents=] as an interactive, scripted user agent according to [[html]].
It MUST assign a unique origin [[html]], shared by all spine-level scripts of the [=EPUB publication=]. That origin [[html]] MUST be unique for each user-specific instance of an EPUB publication in a reading system.
It MUST NOT allow a container-constrained script to modify the [[dom]] of the host EPUB content document or other contents in the EPUB publication and MUST NOT allow it to manipulate the size of its containing rectangle . (Note: Even if a script is not container-constrained, a reading system might impose restrictions on modifications. See the dom-manipulation feature.)
It MAY place additional limitations on the capabilities provided to scripts during execution (e.g., limiting networking).
It MUST extend the navigator object [[!html]] with the epubReadingSystem interface defined in . It also MUST support the dom-manipulation and layout-change features defined in in container-constrained scripting contexts.

If a reading system does not support scripting, it MUST process fallbacks for scripted content as defined in Fallbacks for scripted content documents [[epub-33]].

Local storage

Reading systems MAY block scripts from saving persistent data through cookies and web storage [[html]].

Reading systems that allow local storage [[html]] SHOULD provide methods for users to inspect or delete that data.

Event model

Reading systems SHOULD follow the DOM Event model as per [[html]] and pass UI events to the scripting environment before performing any default action associated with these events.

Reading system developers must ensure that scripts cannot disable critical functionality (such as navigation) to constrain the extent to which a potentially malicious script could impact their reading systems. As a result, although the scripting environment should be able to cancel the default action of any event, some events either might not be passed through or might not be cancelable.

Security considerations

Reading system developers who also support scripting must be aware of the security issues that arise when reading systems execute scripted content. As the underlying scripting model employed by reading systems and browsers is the same, developers must take into consideration the same kinds of issues encountered in web contexts.

Each reading system must establish if it can trust the scripts in a particular document. Reading systems should treat all scripts as untrusted (and potentially malicious), and developers should examine all vectors of attack and protect against them. In particular, developers should consider the following:

an attack against the runtime environment (e.g., stealing files from a user's hard drive);
an attack against the reading system itself (e.g., stealing a list of a user's books or causing unexpected behavior);
an attack of one [=EPUB content document=] against another (e.g., stealing data that originated in a different document);
an attack of an unencrypted script against an encrypted portion of a document (e.g., an injected malicious script extracting protected content);
an attack against the local network (e.g., stealing data from a server behind a firewall).

To limit the possible damage of untrusted scripts, this specification recommends that reading systems establish a unique origin [[html]] allocated to each [=EPUB publication=] (see ). Assigning a unique origin ensures that spine-level scripts [[epub-33]] are isolated from other EPUB publications, and limits access to cookies [[html]], web storage [[html]], etc.

Examples of web APIs that are tied to the concept of "origin" include web storage [[html]] and IndexedDB [[indexeddb]], which EPUB content documents can interact with via scripting. Reading systems that allow users to add/remove publications from a managed library (their "bookshelf") may maintain the publication's unique origin when the publication is removed and subsequently re-imported into the content library. Conversely, reading systems may create a new unique origin for every newly added publication.

This specification also recommends that container-constrained scripts [[epub-33]] not be allowed to modify the DOM of the host EPUB content document and/or manipulate the containing rectangle (see ).

Note that compliance with these recommendations does not guarantee protection from the possible attacks listed above; developers must examine each potential vulnerability within the context of their reading system.

Layout rendering control processing

Fixed-layout documents

[=Reading systems=] MUST support the rendering of fixed-layout documents [[epub-33]].

Fixed-layout properties

The `rendition:layout` property

The default value reflowable MUST be assumed by EPUB reading systems as the global value if no [^meta^] element carrying the rendition:layout property occurs in the package document metadata [[epub-33]].

When the rendition:layout property is set to pre-paginated, reading systems MUST NOT include space between the adjacent content slots when rendering [=synthetic spreads=].

The rendition:layout property values have the following processing requirements:

reflowable: Reading systems MAY apply dynamic pagination when rendering.
pre-paginated: Reading systems MUST produce exactly one page per spine [^itemref^] [[epub-33]] when rendering.

The `rendition:orientation` property

The default value auto MUST be assumed by EPUB reading systems as the global value if no [^meta^] element carrying the rendition:orientation property occurs in the package document metadata [[epub-33]].

The rendition:orientation property values have the following processing requirements:

auto: The reading system determines the orientation in which to render [=EPUB content documents=].
landscape: Reading systems that support multiple orientations SHOULD render EPUB content documents in landscape orientation.
portrait: Reading systems that support multiple orientations SHOULD render EPUB content documents in portrait orientation.

The means by which they convey the intent is implementation specific.

The `rendition:spread` property

Reading Systems MUSt assume the default value auto as the global value if no [^meta^] element carrying the rendition:spread property occurs in the package document metadata [[epub-33]].

The rendition:spread property values have the following processing requirements:

none: Reading systems MUST NOT incorporate spine items in a [=synthetic spread=]. Reading systems SHOULD create a single [=viewport=] positioned at the center of the screen.
landscape: Reading systems SHOULD render a synthetic spread for spine items only when the device is in landscape orientation.
portrait (deprecated): Reading systems SHOULD treat the value "portrait" as a synonym of "both" and create spreads regardless of orientation.
both: Reading systems SHOULD render a synthetic spread regardless of device orientation.
auto: Reading systems MAY use synthetic spreads in specific or all device orientations as part of a [=content display area=] utilization optimization process.

The `rendition:page-spread-*` properties

The rendition:page-spread-left property [[epub-33]] indicates that the given spine item SHOULD be rendered in the left-hand slot of a spread. The rendition:page-spread-right property [[epub-33]] indicates that the given spine item SHOULD be rendered in the right-hand slot of a spread.

The rendition:page-spread-left and rendition:page-spread-right properties apply to both pre-paginated and reflowable content, and they only apply when the reading system is creating [=synthetic spreads=].

The rendition:page-spread-* properties MUST take precedence over whatever value of the page-break-before property [[csssnapshot]] has been set for an [=XHTML content document=].

When a reflowable spine item follows a pre-paginated one, the reflowable one SHOULD start on the next page — as defined by the page-progression-direction attribute [[epub-33]] — when it lacks a rendition:page-spread-* property value.

Reading systems MUST honor rendition:page-spread-* properties on both reflowable and pre-paginated spine items (e.g., by inserting a blank page).

When a pre-paginated spine item follows a reflowable one, the pre-paginated one SHOULD start on the next page (as defined by the page-progression-direction attribute) when it lacks a rendition:page-spread-* property value.

When a reading system encounters two spine items that represent a true spread (i.e., two adjacent spine items with the rendition:page-spread-left and rendition:page-spread-right properties), it SHOULD create the spread with no space between the adjacent pages.

Initial containing block dimensions

XHTML

Reading systems MUST create the initial containing block (ICB) using the width and height expressions declared in the viewport meta tag for [=XHTML content documents=], as defined in Expressing in HTML [[epub-33]]. They MUST clip content positioned outside of the ICB.

If the width or height values in the viewport meta tag contain a non-numeric character but start with a number (e.g., the value includes a unit of length declaration such as "500px"), the number prefix SHOULD be used as the pixel value, otherwise the value MUST be treated as invalid.

Reading systems SHOULD attempt to extract width and height values from a viewport meta tag even if its syntax is invalid.

Reading systems MUST use the first declaration of a width and height property in a viewport meta tag (i.e., ignore repeated declarations).

If the viewport meta does not contain a width or a height value, or if these values are invalid, reading systems MAY supply the values. For example, a reading system may:

consider these as having the values device-width and device-height, respectively; or
look for the previous content document in the [=spine=], if applicable, and use the ICB value defined there; or
consider the content document as erroneous XHTML content altogether.

If an XHTML content document contains more than one viewport meta tags, reading systems MUST use the first in document order to obtain the height and width dimensions. Subsequent declarations MUST be ignored.

When the ICB aspect ratio does not match the aspect ratio of the reading system [=content display area=], reading systems MAY position the ICB inside the area to accommodate the user interface; in other words, added letter-boxing space MAY appear on either side (or both) of the content.

SVG

Reading systems MUST create the initial containing block (ICB) using the dimensions as defined in Expressing the ICB in SVG [[epub-33]] to render [=SVG content documents=].

When the ICB aspect ratio does not match the aspect ratio of the reading system [=content display area=], reading systems should follow the rules for the viewBox and the preserveAspectRatio attributes, as defined in [[SVG]].

Viewport rendering

When rendering [=fixed-layout documents=], the default intent is that the [=content display area=] SHOULD occupy as much of the available [=viewport=] area as possible. Reading systems SHOULD NOT inject additional content such as border, margins, headers, or footers into the viewport.

This specification does not define how the initial containing block [[css2]] is placed within the reading system content display area.

The exposure of reading system control widgets to the user is implementation-specific and not included in the above behavioral expectations.

Reflowable layouts

[=Reading systems=] SHOULD process the reflowable layout properties [[epub-33]].

The `rendition:flow` property

If a reading system supports the specified rendering, it SHOULD use that method to handle overflow content, but MAY provide the option for users to override the requested rendering.

The default global value is auto if no meta element carrying this property occurs in the metadata section [[epub-33]]. Reading systems MAY support only this default value.

The rendition:flow property values have the following processing requirements:

paginated: The reading system SHOULD dynamically paginate all overflow content.
scrolled-continuous: The reading system SHOULD render all [=EPUB content documents=] such that overflow content is scrollable, and SHOULD present the [=EPUB publication=] as one continuous scroll from spine item to spine item (except where locally overridden [[epub-33]]).
scrolled-doc: The reading system SHOULD render all EPUB content documents such that users can scroll overflow content, and SHOULD present each spine item as a separate scrollable document.
auto: The reading system MAY render overflow content using its default method or a user preference, whichever is applicable.

For the rendition:flow-scrolled-continuous property, the scroll direction MUST be defined relative to the block flow direction of the root element of the [=XHTML content document=] referenced by the [^itemref^] element [[epub-33]]. The scroll direction MUST be vertical if the block flow direction is downward (top-to-bottom). It MUST be horizontal if the block flow direction of the root element is rightward (left-to-right) or leftward (right-to-left).

Reading systems MUST ignore the rendition:flow property and its overrides when processing pre-paginated spine items [[epub-33]].

Reading system developers may decide to disregard this restriction, and accept the scrolled-continuous value of rendition:flow as a switch to display each pre-paginated spine item on a long, vertical strip (making it is easier to read on a smartphone or computer). This type of presentation is often referred to as "webtoons". Some publishers already use this possibility. After some further experimentation and incubation, a future version of this specification may introduce this approach as a standard feature for fixed-layout documents. See also the (deferred) github issue 2412.

The `rendition:align-x-center` property

When the rendition:align-x-center property is set on a spine item, reading systems SHOULD render the content centered horizontally within the [=viewport=] or spread, as applicable. This property does not affect the rendering of the spine item, only the placement of the resulting content box.

For reflowable content, reading systems that support this property MUST center each virtual page.

This specification does not define a default rendering behavior when reading systems do not support this property or [=EPUB creators=] do not specify it. Reading systems MAY render spine items by their own design.

The `viewport meta` tag

Except when obtaining the initial containing block dimensions for [=fixed-layout documents=], reading systems MUST ignore rendering instructions in viewport meta declarations.

This restriction applies to both fixed-layout and reflowable documents.

Custom properties

[=Reading systems=] MAY support custom properties provided they do not introduce expressions that conflict behaviorally with the properties defined in the Package rendering vocabulary [[epub-33]].

Media overlays processing

[=Reading systems=] with the capability to render prerecorded audio SHOULD support media overlays [[epub-33]].

If a reading system does not support media overlays, it MUST ignore both:

the media-overlay attribute on [=EPUB manifest | manifest=] [^item^] elements [[epub-33]]; and
item elements where the media-type attribute value equals application/smil+xml.

Loading the media overlay

When a reading system loads a [=package document=], it MUST refer to the [=EPUB manifest | manifest=] [^item^] elements' [[epub-33]] media-overlay attributes to discover the corresponding media overlays for [=EPUB content documents=].

Reading systems MUST support playback for [=XHTML content documents=], and MAY support [=SVG content documents=].

Playback MUST start at the media overlay element which corresponds to the desired EPUB content document starting point. Note that the start of an EPUB content document could correspond to an element at the start or in the middle of a media overlay. When the media overlay document finishes playing, the reading system SHOULD load the next EPUB content document (as specified in the package document [=EPUB spine | spine=]) and also load its corresponding media overlay document, provided that one is given.

Basic playback

Timing and synchronization

Reading systems MUST render immediate children of the [^body^] element [[epub-33]] in a sequence. A [^seq^] element's [[epub-33]] children MUST be rendered in sequence, and playback completes when the last child finishes playing. Reading system MUST render a [^par^] element's [[epub-33]] children in parallel (with each starting at the same time), and playback completes when all the children finish playing. Reading system playback of the media overlay document completes when the body element's last child finishes playing.

Rendering audio

When presented with a media overlay [^audio^] element [[EPUB-33]], reading systems MUST play the audio resource referenced by the src attribute, starting at the clip offset time given by the clipBegin attribute and ending at the clip offset time given by the clipEnd attribute [[epub-33]].

In addition:

If the [=EPUB creator=] has not specified a clipBegin attribute, reading systems MUST assume the value "0".
If the EPUB creator has not specified a clipEnd attribute, reading systems MUST assume the value to be the full duration of the physical media.
If the value of clipEnd exceeds the full duration of the physical media, reading systems MUST assume its value to be the full duration of the physical media.

User-controllable audio playback options SHOULD include timescale modification, in which the user can alter the playback rate without distorting the pitch. The suggested range is half-speed to double-speed.

Rendering EPUB content document elements

When presented with a media overlay [^text^] element [[epub-33]] whose src attribute contains a URL-fragment string referencing a specific part of an EPUB content document, reading systems SHOULD ensure the referenced portion is visible in the [=viewport=]. In addition to [[html]] element ID references and SVG Fragment Identifiers [[svg]], reading systems MAY support other fragment identifier schemes.

During media overlays playback, reading systems with a viewport SHOULD add the class names given by the metadata properties active-class and playback-active-class [[epub-33]] to the appropriate elements, when specified, in the [=EPUB content document=]. Conversely, the class names SHOULD be removed when the playback state changes, as described in Associating style information [[epub-33]].

The active-class and playback-active-class metadata properties are OPTIONAL, and if omitted, reading system behavior is implementation-specific.

Reading system behavior when a fragment identifier [[epub-33]] does not reference an element is also implementation-specific.

Interacting with the EPUB content document

Earlier versions of this specification included some information about embedded audio and video [[epubmediaoverlays-32]]. This feature has been deprecated.

Navigation

Because the media overlay is closely linked to the [=EPUB content document=], it is very easy for reading systems to locate a position in the EPUB content document based on the current position in the media overlay playback. If the user pauses synchronized playback and navigates to a different part of the [=EPUB publication=], synchronized playback MUST resume at that point. For example, if a specific page number in the EPUB content document is the desired location, then this same point is located in the media overlay and playback started there.

This same approach allows for synchronizing the media overlay playback with user selection of a navigation point in the [=EPUB navigation document=]. The reading system loads the media overlay for that file and finds the correct point for starting playback based on the ID of the navigation point target.

[=EPUB creators=] may associate a [=media overlay document=] directly with an EPUB navigation document in order to provide synchronized playback of its contents, regardless of whether the [=XHTML content document=] in which it resides is included in the [=EPUB spine | spine=]. See EPUB navigation document [[epub-33]] for more information.

EPUB creators may associate media overlay document elements with EPUB content document structures such as tables. Reading systems should ensure that media overlay playback remains synchronized with user navigation of table rows and cells. The reading system might also play the corresponding table header preceding the contents of the cell.

Embedded audio and video (deprecated)

Guidance for automatic playback of embedded audio and video is now deprecated.

Refer to its definition in [[epubmediaoverlays-32]] for more information.

Text-to-speech

When a media overlay [^text^] element with no [^audio^] [[epub-33]] sibling element references text within the target [=EPUB content document=], reading systems capable of text-to-speech (TTS) playback SHOULD render the referenced text using TTS.

Reading systems SHOULD use the speech-related information provided in the target EPUB content document to play the audio stream as part of the media overlay rendering.

See EPUB 3 Text-to-Speech Support [[epub-tts-10]] for more information about supporting TTS technologies in [=EPUB publications=].

The media overlay text element's lifespan corresponds to the rendering time of the associated speech synthesis. The implicit duration of the text element (and by inference, of the parent par element) is therefore determined by the execution of the Text-to-Speech engine, and cannot be known at authoring time (factors like speech rate, pauses and other prosody parameters influence the audio output). This also means that reading systems should treat the duration property values set in the package document as approximative when making use of them.

Skippability and escapability

Skippability

Reading systems SHOULD use the semantic information provided by media overlay elements' [^/epub:type^] attribute to offer users the option of skipping content.

When skipping of content is enabled, reading systems MUST suppress playback of any par and seq elements whose epub:type attribute contains a semantic that matches a skippable structure.

Escapability

While playing media overlays, reading systems SHOULD offer users the option to leave ("escape") escapable structures [[epub-33]], which are determined by the presence of an [^/epub:type^] attribute [[epub-33]] with a value from the escapable structures list. If a user opts to escape from an escapable structure, then the reading system MUST continue playback with the next sequential element after the structure.

Processing `property` values

[=Reading systems=] MAY support the vocabulary association mechanisms for processing property data type values [[epub-33]].

This section defines an algorithm for obtaining an expanded URL from a property data type value. It applies only to [=reading systems=] that support the [[epub-33]] vocabulary association mechanisms.

Reading systems that do not support the [[epub-33]] vocabulary association mechanisms MAY process property values as plain [=string=] values [[infra]]. It is not required to support the expansion of these values to URLs to add reading system behaviors based on their presence.

The algorithm describes the process using the terminology and data types defined in [[infra]], and, if successful, results in a [=string=] value with the expanded URL being returned. A null value is returned for invalid properties.

This algorithm takes the following arguments:

value: the property value to process.
attr: the name of the attribute that contains value.
elem: the name of the element that attr is attached to.
doc: the document being processed (e.g., [=package document=], [=media overlay document=], [=epub content document=]).

To obtain an expanded URL, apply the following steps:

Let baseURL, expandedURL, propertyPrefix, and propertyReference be empty [=strings=].
Explanation

In this algorithm:
- baseURL will hold the base URL associated with the value, whether this URL is assigned by the EPUB creator, corresponds to a default vocabulary, or comes from a reserved prefix.
- expandedURL will hold the final URL that results from the concatenation of the base URL and property reference.
- propertyPrefix will hold the property's prefix [[epub-33]] (i.e., the value before the colon). Properties from a default vocabulary will not have a prefix, but all others will.
- propertyReference will hold the property's reference [[epub-33]] (i.e., the value after the prefix). All valid properties require a reference.
Obtain the values of propertyPrefix and propertyReference as follows:
1. If value does not contain a colon (U+003A), set propertyReference to value.
  
  Explanation
  
  If a property value does not have a colon, it does not have a prefix. In this case, the value is drawn from the default vocabulary as described in the next step of the algorithm.
2. Otherwise, if value begins with a colon, the value is invalid. Return null.
  
  Explanation
  
  A colon at the beginning of the value is invalid as it indicates the prefix is not set.
3. Otherwise, split value on the first colon and set propertyPrefix to the string before the colon and set propertyReference to the string after the colon.
If propertyReference is not a valid [=path-relative-scheme-less-URL string=], as required by the property data type definition [[epub-33]], the value is invalid. Return null.

Explanation

The path-relative-scheme-less-URL string definition has a number of restrictions that apply to the reference whether it has a prefix or not.

For example, the reference must not begin with a [=URL-scheme string=] followed by a colon. This restriction means that the following is not a valid property value as the second colon could represent a scheme: foo:bar:baz/qux.

There are also restrictions on what characters must be percent encoded.
Obtain the value of baseURL as follows:
1. If propertyPrefix is an empty string:
  1. If attr is [^/epub:type^] [[epub-33]], set baseURL to
    http://idpf.org/epub/vocab/structure/#
  2. Otherwise, if elem is the package document [^meta^] element [[epub-33]] and attr is scheme, the property value is invalid. Return null.
  3. Otherwise, if elem is the package document [^meta^] element [[epub-33]], set baseURL to
    http://idpf.org/epub/vocab/package/meta/#
  4. Otherwise, if elem is the package document [^link^] element [[epub-33]], set baseURL to
    http://idpf.org/epub/vocab/package/link/#
  5. Otherwise, if elem is the package document [^item^] element [[epub-33]], set baseURL to
    http://idpf.org/epub/vocab/package/item/#
  6. Otherwise, if elem is the package document [^itemref^] element [[epub-33]], set baseURL to
    http://idpf.org/epub/vocab/package/itemref/#
  Explanation
  
  If the property value does not have a prefix, then this step assigns the default vocabulary URL to use based on the attribute or element to which it belongs. When an element in the package document has more than one attribute that takes a property data type, those attributes share the same default vocabulary. For this reason, it is not necessary to check both the element and attribute to determine what URL to assign.
  
  The one attribute in EPUB 3 that does not have a default vocabulary is the scheme attribute [[epub-33]]. A scheme value without a prefix is invalid.
2. Otherwise:
  1. If a prefix attribute is declared on the document element of doc, and the attribute contains a prefix that matches propertyPrefix, set baseURL to the URL associated with the prefix declaration.
  2. Otherwise, if propertyPrefix matches a reserved prefix [[epub-33]] for doc, set baseURL to the URL associated with the reserved prefix.
  Explanation
  
  When a property value has a prefix, the first place to check for its base URL is in a prefix attribute declaration on the document element.
  
  If the author has not assigned a URL for the prefix, the next step is to check if the prefix matches one of the reserved prefixes.
  
  Note that author-assigned prefix URLs override the reserved prefix URLs.
If baseURL is an empty string, the property value is invalid. Return null.

Explanation

If the base URL is empty at the end of this processing step, then either the prefix is not mapped or reserved, or the element or attribute being processed does not accept property data types as defined in [[epub-33]].

Without a base URL, it is impossible to generate an expanded URL, so the value is invalid.
Set expandedURL to the concatenated values of baseURL and propertyReference. Do not add a separator when concatenating the values.
If expandedURL is not a [=valid URL string=], the value is invalid. Return null.

Otherwise, return expandedURL.

Explanation

Although an expanded value may be obtained, it is not necessarily the case that it is a valid URL. This is only likely to occur when the EPUB creator assigns an invalid base URL to a prefix.

Reading systems do not have to [=url parser | parse the resulting URL=] [[url]] or attempt to dereference the resulting expanded URL. Expanding a property data type value to a full URL only ensures a reading system has encountered the value it expects (i.e., because different EPUB creators can assign the same prefix to different URLs, two values may appear the same until expanded).

Security and privacy

Overview

The particularity of an [=EPUB publication=] is its structure. The EPUB format provides a means of representing, packaging, and encoding structured and semantically enhanced web content — including HTML, CSS, SVG, and other resources — for distribution in a single-file container.

For [=reading systems=], this means that the security and privacy issues are primarily based on the features of those formats, and closely mirror the threats presented by web content generally.

Reading system developers also have a dual responsibility of both ensuring the security and privacy of their applications and helping limit the threats to users from the content that renders within them. The rest of this section explores the risk model of EPUB 3 with the aim of helping developers recognize and mitigate these risks.

For the risks associated with the authoring of EPUB publications, refer to the security and privacy section of [[epub-33]].

Threat model

The greatest threats to users come from the content they read [[epub-33]], and the first line of defense against these attacks is the reading systems they use. Users expect that reading systems act as safeguards against malicious content and are often unaware that [=EPUB publications=] are susceptible to the same security risks as web sites.

But although reading systems are relied on to provide security and privacy, they can also pose unintended threats to users depending on how information is handled. Tracking user information to optimize experiences is a common need, for example, but done without user permission and reading systems can run afoul of legal privacy requirements.

This section outlines some of the key threats that reading system developers must take into consideration, with further details and recommendations in the following sections.

Scripting

Malicious scripts present several attack vectors against reading systems. If local storage is not secure, for example, they can attempt to compromise the user's data. Provided with network access, they may attempt unauthorized collection of user data.

More detailed discussion of these issues and how to mitigate them is provided in .

Malicious content

EPUB publications may contain resources designed to exploit security flaws in reading systems or the operating systems they run on. Attackers may also try to gain access to [=remote resources=] using file indirection techniques, such as symbolic links or file aliases.

The lack of a standard method of signing EPUB publications means that reading systems cannot always verify whether the content has been tampered with between authoring and loading in the device.

Remote resources

[=Remote resources=] present the same risks as any EPUB publication loaded from an untrusted source. Even if the publisher of the EPUB publication is trusted, remote resources may be compromised.

Calls to remote resources can also be used to track information about users (e.g., through server logs). Reading systems should limit the information they expose through HTTP requests to only what is essential to obtain the resource.

The origin of an EPUB is both unknown to the [=EPUB creator=] and specific to each reading system implementation. Consequently, if the EPUB creator hosts remote resources on a web server they control, the server effectively cannot use security features that require specifying allowable origins, such as headers for CORS, Content-Security-Policy, or X-Frame-Options.

External links

Like remote resources, external links may be used to trick unwitting users into opening malicious resources on the web designed to exploit the reading system or operating system.

Likewise, reading systems should also avoid exposing potentially identifying information about users through the traversal of links (e.g., not using tracking identifiers or exposing unnecessary information about the user's environment).

User-generated content

User-generated content within a reading experience, for example through text areas or other interactive components, could pose a threat to reading system security or user privacy if the content is not properly secured. More details on scripting security are provided in .

Collection of user data

Collecting information about the user and their reading habits without obtaining their permission can violate their privacy, even if the information is only intended for internal use.

Attempting to profile users based on their reading habits or through metadata in their publication (e.g., accessibility preferences) can expose users to unintended harms.

Additionally, the security considerations that apply to [[xml]] and [[zip]] files also apply to the package document and the Open Container Format, respectively. See the "Security Consideration" sections of the Media Type registrations for the application/oebps-package+xml and the application/epub+zip formats for further details.

Recommendations

The strongest measure that reading system developers can take for privacy is to specify the data they intend to collect and use about the user and/or their reading behavior and seek the consent of users to obtain it. They SHOULD also allow personalization and control over this information.

If a reading system allows users to store persistent data, especially personally identifiable information, it SHOULD treat that data as sensitive and not allow access to it by third parties.

It is understood that the collection of some user data may be required for the sale, delivery, and operation of an [=EPUB publication=], particularly on platforms where the sale of an EPUB publication and the method of reading it are connected. In these cases, the reading system SHOULD identify the data being collected, how it is used, and allow for user opt-outs (retailers may choose to inform users by other means, however, such as when a user creates an account on their web site). Anonymization of any collected data is RECOMMENDED for the privacy and the security of the user and reading system.

It is also understood that user data may be required or helpful for some reading system affordances. In these cases, anonymization is also RECOMMENDED. Reading systems also SHOULD inform users of what data is needed, what it is to be used for, and to provide methods to opt-out.

Content processors — defined as entities that handle the ingestion of EPUB content for distribution, display, or sale — also need to be aware of the potential risks in ingestion. It is advised that content processors check content for malicious content on ingestion, in addition to the validation steps that usually occur. This could include running virus scans, validating external links and remote resources, and other precautions.

When processing XML documents, a reading system SHOULD NOT resolve external identifiers in DOCTYPE, ENTITY and NOTATION declarations [[xml]]. Reading systems SHOULD also consider security risks related to internal or external XML entities like, for example, DoS attacks also known as "Billion laughs attacks" or "XML external entity attacks".

Additional security recommendations for external links, network access and scripting are available in , , and , respectively.

epubReadingSystem object

[=Reading systems=] act as the core rendering engines of EPUB publications and provide a scripting environment based on the [[dom]] specification. So, although this interface definition uses the [[webidl]] notation for implementation by reading systems, web browsers generally do not have to implement these objects.

Interface definition

This specification extends the {{Navigator}} object [[html]] as follows.

[Exposed=(Window)]
interface EpubReadingSystem {
    boolean hasFeature(DOMString feature, optional DOMString version);
};

partial interface Navigator {
    [LegacyUnforgeable, SameObject] readonly attribute EpubReadingSystem epubReadingSystem;
};

This specification does not define an epubReadingSystem property extension for the {{WorkerNavigator}} object [[html]]. Reading systems therefore do not have to expose the epubReadingSystem object in the scripting context of Workers, and [=EPUB creators=] cannot rely on its presence.

Description

The Navigator.epubReadingSystem object provides an interface through which a [=scripted content document=] can query information about a user's reading system.

Reading systems MUST expose the epubReadingSystem object on the navigator object of all loaded scripted content documents, including any nested container-constrained scripting contexts [[epub-33]]. Reading systems MUST ensure that the epubReadingSystem object is available no later than when the DOMContentLoaded event is triggered [[html]].

Reading systems implementations may create cloned instances of the epubReadingSystem object in scripted content documents for technical feasibility reasons. In such cases, the reading system must ensure they consistently maintain the object's state — as reflected by the values of its properties and methods — across all copied instances.

Properties

This specification used to define the name, version, and the layoutStyle properties, but these are now deprecated [[epub-33]]. For more information refer to their definitions in [[epubcontentdocs-32]] (for name and version) and in [[epubcontentdocs-301]] (for layoutStyle).

Methods

hasFeature

Description

The hasFeature method returns a boolean value indicating whether the reading system supports any version of the specified feature, or undefined if the reading system does not recognize the specified feature.

The optional version parameter allows [=EPUB creators=] to query custom features that could change in incompatible ways over time. The return value indicates support only for the specified version of the feature.

Features defined in this specification are versionless. If a reading system supports a feature defined in this specification, it MUST ignore any supplied version parameter and return a true value.

var feature = "dom-manipulation";

var conformTest = navigator.epubReadingSystem.hasFeature(feature);

alert("Feature " + feature + " supported?: " + conformTest);

Features

The following table lists the set of features that reading systems that support the epubReadingSystem object MUST recognize. When the features are queried from the hasFeature method, reading systems MUST return a boolean value indicating their support.

Name	Description
`dom-manipulation`	Scripts may make structural changes to the document’s DOM (applies to spine-level scripting [[epub-33]] only).
`layout-changes`	Scripts may modify attributes and CSS styles that affect content layout (applies to spine-level scripting [[epub-33]] only).
`touch-events`	The device supports touch events, and the reading system passes touch events to the content.
`mouse-events`	The device supports mouse events, and the reading system passes mouse events to the content.
`keyboard-events`	The device supports keyboard events, and the reading system passes keyboard events to the content.
`spine-scripting`	Indicates whether the reading system supports spine-level scripting [[epub-33]] (e.g., so a container-constrained script [[epub-33]] can determine whether any actions that depend on scripting support in a [=top-level content document=] have any chance of success before attempting them).

Reading system developers MAY add additional features, but future versions of this specification could append to this list in ways that might conflict or be incompatible with any such custom additions.

Change log

Note that this change log only identifies substantive changes since EPUB 3.2 — those that may affect the conformance of [=EPUB reading systems=].

For a list of all issues addressed, refer to the working group's issue tracker.

Substantive changes since the Recommendation of 2023-05-25

No substantive changes were made.

Substantive changes since the Candidate Recommendation of 2022-05-12

01-Feb-2023: Removed reference to getOverrideStyle in DOM Level 2 as it was dropped from the DOM Living Standard. See pull request 2531.
11-Jan-2023: Added note advising reading system developers to support package metadata directionality even though marked as under-implemented for authoring. See pull request 2515.
11-Jan-2023: Removed support description for under-implemented features. See pull request 2515.
06-Jan-2023: Reduced the requirement to support prefixed CSS properties to a recommendation. See pull request 2514.
06-Jan-2023: Reduced the requirement to use alternative text for non-text elements in the navigation document to a recommendation due to the lack of support for both. See pull request 2513.
05-Jan-2023: Removed the processing requirements for linked records. See pull request 2512.
11-Nov-2022: Added requirement to replace unsupported non-text elements with their text alternatives when generating non-HTML navigation widgets. See issue 2477.
13-Oct-2022: Added sections to explain expectations for error handling and reporting. See issue 2454.
11-Oct-2023: Additional text sketching the RS behavior in the case of erroneous ICB setting. See issue 2442.
06-10-2022: Moved the restriction on XML external identifiers from the XML conformance clause to the security and privacy section, adding an additional note on security risks on internal or external entities. See issue 2433 and issue 2477.
23-Sep-2023: Added a note on a possible future feature, whereby the value of rendition:flow would control the publication of webtoon-like publications. See issue 2412.
19-Sept-2022: Removed ARIA extension section as the HTML specification already contains ARIA support requirements. See issue 2431.
14-Sept-2022: Integrated the reading system support requirements for unsupported features that were still in the EPUB 3.3 specification. See issue 2424.
28-Aug-2022: The guidelines for rendering embedded timed media in Media Overlays have been deprecated. See issue 2397.
28-July-2022: Restructured the vocabulary association mechanisms section as an algorithm for obtaining an expanded URL. See issue 2378.
22-July-2022: The name and version properties of the epubReadingSystem object have been deprecated. See issue 1872.
19-July-2022: ZIP containers with content split into segments have been disallowed in general. See issue 2360.
24-June-2022: Removed duplicate requirement not to use hreflang value for processing purposes. See pull request 2343.
17-June-2022: Add recommendation to alert user before opening URLs with a scheme and clarify the external links section to account for more than just web schemes. See issue 2320.
17-June-2022: Clarify support for the vocabulary association mechanisms is optional. See issue 2317.
07-June-2022: The usage of File URLs has been disallowed. See issue 2324.
07-June-2022: Noted that unsigned EPUB publications represent a security risk and added recommendation to treat sideloaded unsigned publications as untrusted. See issue 2265.
07-June-2022: Updated privacy and security recommendations to use normative language.
27-May-2022: Added reading system conformance section. See issue 2271.
27-May-2022: Added recommendation to only load remote resources referenced via https. See issue 2263.
20-May-2022: Removed the recommendation to prevent access to persistent storage from "unrelated documents". This recommendation conflicts with, and is made redundant by, the unique origin requirement introduced in this revision. See issue 2264.
17-May-2022: Added an index of terms. See issue 2260.

Substantive changes since EPUB 3.2

31-Mar-2022: Moved custom attribute authoring requirements to the authoring specification. Added reading system handling of custom properties. See issue 2134.
17-Mar-2022: Added requirement to suppress playback of skippable elements in media overlays Documents. See issue 2066.
11-Feb-2022: Fix the contradictory support statements for media overlays. Support is recommended when rendering of prerecorded audio is supported, as in previous versions of EPUB 3. See issue 1991.
04-Feb-2022: Changed the non-normative security considerations for controlling network access, opening external links, and managing local storage to normative recommendations. See issue 1957.
04-Feb-2022: Expanded the section on security and privacy to include new sections on the threat model for reading systems and additional recommendations for ensuring security and privacy. See issue 1871, issue 1872, issue 1875 and issue 1876.
03-Feb-2022: Reduced the requirement to support deobfuscation to a recommendation. See issue 1873.
19-Jan-2022: Elevated default statements for the rendition:spread and rendition:orientation properties to requirements, to align with rendition:layout. See issue 1936.
08-Dec-2021: page-spread-center is now an alias for spread-none. See issue 1929.
10-Nov-2021: Proper definition of the content URL and handling of relative URLs. See issue 1374 and issue 1888.
01-Nov-2021: Added a statement on the reading system behavior when item references are repeated in the spine. See issue 1686.
25-Oct-2021: Clarify that reading systems must render non-linear resources when they are hyperlinked to by a user. See issue 1864.
27-Aug-2021: Added accessibility bullet to cover the need for zooming, particularly for fixed-layout documents. See issue 1776.
27-Aug-2021: Remove the recommendation to support text search and selection in SVGs. Replacing with a more general bullet on search accessibility to avoid defining requirements on reading system UI. See issue 1774.
09-July-2021: Restored the custom attributes section due to known usage but without reference to the attribute registry. See issue 1602.
09-July-2021: Removed recommendation to use the first language tag to determine an unspecified page progression direction. See issue 1482.
18-June-2021: Moved requirements for supporting SSML, PLS lexicons and CSS 3 Speech to the EPUB 3 Text-to-Speech Support note. See issue 1690.
20-May-2021: Providing a shared and unique origin for scripts is a requirements for reading systems that support scripting. See issue 1659.
20-May-2021: Removed requirement for reading systems to be conformant xml:base processors. See pull request 1678.
12-May-2021: Added additional requirement that reading systems ignore property values that expand to invalid URL strings and property values with empty references. See issue 1673.
12-May-2021: Changed all references to URIs/IRIs to URLs and references to RFCs 3986 and 3987 to the URL standard. See issue 808.
06-May-2021: Recommend that reading systems support references to HTML target elements and SVG fragment identifiers in textref attributes and the text element's src attribute. Support for other fragment identifier schemes is optional. See issue 1586.
23-Apr-2021: Clarified that reading systems should attempt to process invalid file and path names. See issue 1629
16-Apr-2021: Removed the section on custom attributes. See Working Group Resolution.
15-Apr-2021: Remove the reference to "presentation logic". See issue 1516 and Working Group Resolution.
12-Apr-2021: The section has been marked as "at-risk". See Working Group resolution.
09-Apr-2021: Added a new section dedicated to accessibility and removed the outdated reference to the defunct appendix in the Accessibility specification. See issue 1608.
09-Apr-2021: Added section clarifying all the conformance requirements on establishing the primary language and base direction of publication resources. See pull request 1613.
01-Apr-2021: Added section clarifying how absolute URLs are created from relative in the package document. See pull request 1468.
30-Mar-2021: Restructured the document to remove the rendundant conformance sections and requirements that were only used as locators when this specification was combined with the authoring requirements. See pull request 1597 and pull request 1609.
23-Mar-2021: Added requirement to prevent top-level navigation to data URLs. See issue 1564.
23-Mar-2021: Changed "suppressing" of non-linear content to "skipping" when traversing the spine to clarify that the intention is not to remove all access to such content. See issue 1480.
10-Mar-2021: Changed restriction against using resources not listed in the package document to a recommendation not to use. See issue 810.
09-March-2021: the statement on unique identifiers has been set to non-normative, following the discussion and Working Group resolution. See issue 1310.
08-Mar-2021: Remove unnecessary requirement to assume default value for rendering metadata. See issue 1313.
05-Mar-2021: Added requirement for reading systems to collapse whitespace in DCMES and meta elements per the [[infra]] specification definition. See issue 1295.
26-Feb-2021: Clarified the trimming of leading and trailing whitespace is to be done in accordance with the [[infra]] specification definition, and removed the exception that meta element properties may define their own whitespace handling rules. See issue 1295.
19-Feb-2021: Updated the scripting security considerations so that the text recommends assigning a unique origin to each EPUB publication for security rather than domain isolation at the EPUB content document level. See issue 1156.
15-Feb-2021: Clarified the requirements for presenting nav elements in the navigation document. The toc nav is now the only required element, the page-list nav is recommended when present, and all others are optional. See issue 975.
10-Feb-2021: A very first draft for has been added.
04-Feb-2021: Added explicit requirement that reading systems not use the language in dc:language elements as the language of resources.
02-Feb-2021: Added base direction determination rules for the dir attribute accounting for the addition of the new auto value. See issue 1491.
02-Feb-2021: Noted that language information in the new hreflang attribute on link elements is not authoritative. See issue 1488.
24-Dec-2020: The creation of a release identifier [[epubpackages-32]] is no longer defined. See issue 1440.
06-Nov-2020: Reading systems are now required to not resolve external identifiers in doctype declarations. See issue 1338.
05-Nov-2020: Generalized the restriction on custom attribute namespace URIs to exclude all of idpf.org and w3.org. See issue 1388.
30-Sept-2020: The structure of the EPUB core specifications has been simplified to ease understanding and access to information. This specification now consolidates the reading system requirements from the EPUB 3.2 specification together with the Packages, Content Documents, OCF and media overlays specifications. The EPUB 3.3 core specification now focuses only on authoring requirements.

Introduction

Overview

Terminology

Relationship to other specifications

Relationship to HTML

Relationship to SVG

Reading system conformance

Requirements

Error handling

Error reporting

Publication resource processing

Core Media types

Foreign resources

Resource locations

Data URLs

File URLs

XML processing

Internationalization

Network access

External links

Open Container Format (OCF) processing

OCF abstract container

URL of the root directory

File names

META-INF directory

OCF ZIP container

Font obfuscation

Package document processing

Base direction

Unique identifier

Metadata

Manifest

Spine

Spine overrides

Collections

Legacy features

EPUB content document processing

XHTML content documents

HTML extensions

RDFa

Content switching (deprecated)

The epub:trigger element (deprecated)

Custom attributes

HTML deviations and constraints

Microdata

MathML

Embedded SVG

Embedded SVG and CSS

Form submission

SVG content documents

Cascading Style Sheets (CSS)

Scripting

Local storage

Event model

Security considerations

Navigation document processing

Layout rendering control processing

Fixed-layout documents

Fixed-layout properties

The rendition:layout property

The rendition:orientation property

The rendition:spread property

The rendition:page-spread-* properties

Initial containing block dimensions

Viewport rendering

Reflowable layouts

The rendition:flow property

The rendition:align-x-center property

The viewport meta tag

Custom properties

Media overlays processing

Loading the media overlay

Basic playback

Timing and synchronization

Rendering audio

Rendering EPUB content document elements

Interacting with the EPUB content document

Navigation

Embedded audio and video (deprecated)

Text-to-speech

`META-INF` directory

The `epub:trigger` element (deprecated)

The `rendition:layout` property

The `rendition:orientation` property

The `rendition:spread` property

The `rendition:page-spread-*` properties

The `rendition:flow` property

The `rendition:align-x-center` property

The `viewport meta` tag

Processing `property` values