Copyright © 1999-2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the EPUB 3 Working Group as a Working Draft. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-epub-wg@w3.org (subscribe, archives).
Publication as a Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 15 September 2020 W3C Process Document.
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 Systems.
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. As a result, there is no single set of rules that all Reading Systems have to follow. Rather, the rendering requirements are broken down based on the Reading System's capabilities and the features its supports.
Moreover, a great deal of flexibility is provided to developers to create unique user interfaces, such as their bookshelves. As a result, metadata processing requirements are often quite minimal, for example.
So, although this specification identifies the formal requirements for Reading Systems, it is not possible to read this document in isolation. Developers will also need to familiarize themselves with the full content structure of an EPUB Publication 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.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, NOT REQUIRED, OPTIONAL, RECOMMENDED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This section is non-normative.
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 will need to keep track of the changes to HTML, and the technologies it references, and ensure that their systems are kept up to date.
This specification does not require EPUB Reading Systems to support scripting, HTML forms or the HTML 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 HTML forms is not compulsory, a conformant Reading System might not be a fully-conformant HTML user agent.
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 will need to keep track of changes to the SVG standard and ensure that their systems are kept up to date.
Reading Systems MUST process Publication Resources [EPUB-33].
Reading Systems MAY support an arbitrary set of Foreign Resource types, and MUST process fallbacks for unsupported Foreign Resources as defined in Foreign Resources [EPUB-33] if not.
Reading Systems SHOULD support remote resources, as defined in Resource Locations [EPUB-33].
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, it MUST also prevent data URLs from opening as though they are Top-level Content Documents.
There is no final agreement in the WG on how to precisely formulate the restrictions on the usage of data-url-s. The current formulation relies on the top-level browsing contexts term but that may not be adequate (e.g., if the top level document is an SVG file).
The generic goal is to disallow (for, e.g., security reasons) using, e.g., an
<a>
element referring to a data URL, while still making it possible to,
use a data url in, say, an <img>
element. Browsers implement similar
restrictions, but the WG would need a generic, browser-independent terminology to include in the
EPUB Reading System specification.
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 pre-recorded audio, it MUST support the audio Core Media Type Resources [EPUB-33] and SHOULD support Media Overlays [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 other video codecs, or none at all. Reading System developers need to take into consideration factors such as breadth of adoption, video playback quality, and technology usage royalty requirements when making the choice to implement video in either format, or both.
A Reading System MUST be all of the following:
a conformant processor as defined in [XML-NAMES].
a conformant application as defined by [XMLBase].
In addition, when processing XML documents, it MUST NOT resolve external identifiers [XML].
Reading Systems MUST process the Package Document [EPUB-33].
Reading Systems MUST honor all presentation logic expressed through the Package Document [EPUB-33] (e.g., the reading order, fallback chains, page progression direction and fixed layouts).
To obtain an absolute IRI reference from a relative IRI reference [RFC3987] in the Package Document, Reading Systems MUST use the Base IRI [RFC3986] of the Package Document.
The Base IRI of the Package Document is the combination of the Base IRI of the EPUB Container together with the path to Package Document (relative to the Root Directory) when an EPUB Publication is zipped.
This specification does not require a specific IRI scheme for referencing the path to the Package Document within the EPUB Container.
If the dir
attribute 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].
Reading Systems SHOULD NOT depend on the unique-identifier
attribute 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, might require inspecting other metadata, such as the titles or
authors.
Reading Systems MUST
strip and
collapse ASCII whitespace [Infra] from Dublin Core
[DC11] and meta
element values [EPUB-33]
before processing.
identifier
elementTo determine whether an identifier
conforms to an established system or has been
granted by an issuing authority, Reading Systems SHOULD check for
an identifier-type
property [EPUB-33].
title
elementReading Systems MUST recognize the first
title
element 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 title
elements.
language
elementThe language(s) of the EPUB
Publication specified in language
elements are advisory. Reading
Systems MUST use the language information associated with a
resource to determine its language.
creator
elementWhen determining display priority, Reading Systems MUST use the
document order of creator
elements 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).
meta
elementIf a Reading System does not recognize the scheme
attribute value, it SHOULD treat the value of the element as a string.
Reading Systems SHOULD ignore all meta
elements whose
property
attributes define expressions they do not recognize. A Reading
System MUST NOT fail when encountering unknown expressions.
link
elementRetrieval of Remote Resources is OPTIONAL.
The language identified in an hreflang
attribute is not authoritative. Language
information defined in a linked resource determines its language.
Reading System do not have to use or present linked resources, even if they recognize the
relationship defined in the rel
attribute.
In the case of a linked metadata record [EPUB-33], Reading Systems MUST NOT skip processing the metadata expressed in the Package Document and only use the information expressed in the record. Reading Systems MAY compile metadata from multiple linked records; they do not have to select only one record.
When it comes to resolving discrepancies and conflicts between metadata expressed in the
Package Document and in linked metadata records, Reading Systems MUST use the document order of link
elements in the Package Document
to establish precedence (i.e., metadata in the first linked record encountered has the
highest precedence and metadata in the Package Document the lowest, regardless of whether
the link
elements occur before, within or after the package metadata
elements).
Reading Systems MUST ignore any instructions contained in linked resources related to the layout and rendering of the EPUB Publication.
It MUST ignore proprietary metadata properties that pertain to layout expressions if they conflict behaviorally with the property semantics defined in § 6.1 Fixed-Layout Properties.
When an href
attribute contains a relative IRI, Reading Systems MUST use the IRI of the Package Document as the base when resolving to an absolute
IRI.
Reading Systems MAY optimize the rendering depending on the properties set
in the properties
attribute (e.g., disable a rendering process or use a fallback).
Reading Systems MUST ignore values of the properties
attribute
they do not recognize.
It SHOULD NOT use non-Publication 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 Media Type of a given Publication Resource MUST traverse the fallback chain until it has identified at least one 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 specific properties [EPUB-33] of that resource, otherwise it SHOULD honor the EPUB Creator's preferred fallback order. If a Reading System does not support any resource in the fallback chain, it MUST alert the reader that content could not be displayed.
When manifest fallbacks [EPUB-33] are provided for Top-level Content Documents, Reading Systems MAY choose from the available options in order to find the optimal version to render in a given context (e.g., by inspecting the properties attribute for each).
Reading Systems MUST provide a means of rendering the EPUB Publication in
the order defined in the spine
, which includes: 1) recognizing the first primary
itemref
as the beginning of the default reading order; and, 2) rendering successive
primary items in the order given in the spine
.
When a user traverses the default reading order defined in the spine [EPUB-33], a Reading
System MAY automatically skip itemref
elements marked as
non-linear (excluding when a user specifically activates a hyperlink to such items). Reading Systems
MAY also provide the option for users to select whether non-linear
content is skipped by default or not.
When the default
value of the page-progression-direction
attribute is
specified, the Reading System can choose the rendering direction. The default
value MUST be assumed when the attribute is not specified. In this case, the
reading system SHOULD choose a default
page-progression-direction
value based on the first language
element.
Reading Systems MUST ignore the page progression direction defined in pre-paginated
XHTML Content Documents. The
page-progression-direction
attribute defines the flow direction from one
fixed-layout page to the next.
Reading Systems MUST ignore all metadata properties expressed in spine
itemref
properties
attribute that they do not recognize.
In the context of this specification, support for collections in Reading Systems is OPTIONAL. Reading Systems MUST ignore
collection
elements that define unrecognized roles.
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.
Reading Systems SHOULD recognize embedded ARIA markup and support exposure of any given ARIA roles, states and properties to platform accessibility APIs [WAI-ARIA].
In addition to the requirements in § 9. Processing Structural Semantics, a Reading
System has to process the epub:type
attribute as follows in XHTML Content
Documents:
Reading System support for the attribute processing model [RDFA-CORE] is OPTIONAL.
Reading System support for the attribute processing model is OPTIONAL, as is the conversion to JSON [Microdata].
Reading Systems with Text-to-Speech (TTS) capabilities SHOULD support SSML attributes [EPUB-33].
ssml:ph
attributeReading Systems that support the SSML Attributes and PLS documents [EPUB-33] MUST honor the defined precedence rules for these two constructs.
ssml:alphabet
attributeReading Systems that support the SSML Attributes
feature of this specification SHOULD support the IPA
alphabet [IPA], as expressed by the value
"ipa
".
Use of the switch
element is deprecated [EPUB-33]. Refer to its definition in [EPUBContentDocs-301] for
implementation information.
epub:trigger
Element (Deprecated)Use of the trigger
element is deprecated [EPUB-33].
Refer to its definition in [EPUBContentDocs-301] for implementation information.
Vendors MAY introduce functionality not defined in this specification to enhance the rendering of EPUB Publications.
To facilitate this experimentation, vendors MAY define custom attributes for use in XHTML Content Documents provided they are from a foreign namespace, which is defined as a namespace [XML-NAMES] that does not include either of the following domains in its URI's authority component [RFC3986]:
w3.org
idpf.org
Custom attributes, and the behaviors associated with them, MUST NOT alter the integrity of an EPUB Publication.
To facilitate interoperability of custom attributes across Reading Systems, vendors are strongly encouraged to document any extensions they implement in [AttributeExtensions].
A Reading System has to support MathML embedded in XHTML Content Documents as follows:
It MUST be an input-compliant renderer for Presentation MathML, as defined in the [MATHML3] specification.
It MAY support rendering of Content MathML found in
annotation-xml
elements.
If it has a Viewport, it MUST support visual rendering of Presentation MathML.
Reading Systems may choose to use third-party libraries such as MathJax to provide MathML rendering.
Reading Systems MUST process SVG embedded in XHTML Content Documents as defined in § 4.2 SVG Content Documents.
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.
Reading System support for the submission of [HTML] forms is OPTIONAL. A Reading System might, for example, prevent form submissions by limiting access to networking.
Reading Systems MUST process SVG Content Documents [EPUB-33].
A Reading System has to process SVG Content Documents and SVG embedded in XHTML Content Documents as follows:
Unless explicitly defined by this specification as overridden, it MUST process SVG Content Documents using semantics defined by the [SVG] specification and honor any applicable user agent conformance constraints expressed therein.
It MUST meet the Reading System conformance criteria defined in § 4.4 Scripting.
If it has a Viewport, it MUST 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, it MUST also conform to the constraints defined in § 4.1.2.2.1 Embedded SVG and CSS.
It SHOULD support user selection and searching of text within SVG elements.
It MUST recognize the value
"http://www.idpf.org/2007/ops
" of the requiredExtensions
attribute as representing the occurrence of XHTML Content Document fragments (e.g., when the
attribute is included on the foreignObject
element or children of the
switch
element).
If a Reading System has a Viewport, it MUST support the visual rendering of XHTML Content Documents via CSS [EPUB-33].
A Reading System that supports CSS has to process it as follows:
It MUST support the official definition of CSS as described in the [CSSSnapshot].
It SHOULD support all applicable modules in [CSSSnapshot] that have reached at least Candidate Recommendation status [W3CProcess] (and are widely implemented).
It MUST support [TrueType], [OpenType], [WOFF] and [WOFF2] font resources
referenced from @font-face
rules.
It MUST support all prefixed properties defined in CSS Style Sheets — Prefixed Properties [EPUB-33].
In addition to supporting CSS properties as defined above, its user agent style sheet SHOULD support the [HTML] suggested default rendering.
It SHOULD apply EPUB Creator style sheets as written to EPUB Content Documents.
It 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, the getOverrideStyle
method [DOM-Level-2-Style], or [HTML] style
attributes.
It SHOULD allow users to override the EPUB Creator's style sheets as desired.
Reading System developers are strongly encouraged to implement CSS support at the level of major browsers and to publicly document their user agent style sheets and how they interact with EPUB Creator's style sheets.
Reading Systems with Text-to-Speech (TTS) capabilities SHOULD support [CSS3-Speech].
Reading Systems SHOULD support scripting [EPUB-33].
Reading System support for scripting depends on the context in which it is used:
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 might 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 NOT allow a container-constrained script to modify the DOM of the parent 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, the Reading System MAY impose restrictions on modifications (see also the dom-manipulation feature).)
It MAY place additional limitations on the capabilities provided to scripts during execution (e.g., limiting networking).
It MUST implement the JavaScript navigator
extension object epubReadingSystem
defined in § A. JavaScript
epubReadingSystem Object. It also MUST
support the dom-manipulation
and layout-change
features defined in
§ A.4.1.2
Features in container-constrained scripting contexts.
If a Reading System that does not support scripting, it MUST process fallbacks for scripted content as defined in Fallbacks for Scripted Content Documents [EPUB-33].
Reading Systems with Text-to-Speech (TTS) capabilities SHOULD support PLS lexicons [EPUB-33].
A Reading System that supports PLS lexicons has to process them as follows:
Reading Systems with Text-to-Speech (TTS) capabilities SHOULD support [PRONUNCIATION-LEXICON].
It MUST process PLS documents as defined in [PRONUNCIATION-LEXICON].
It MUST apply the supplied pronunciation instructions to all text nodes in the current XHTML Content Document whose language [HTML] matches the language for which the pronunciation lexicon is relevant [PRONUNCIATION-LEXICON]. The algorithm for matching language tags is defined in [BCP47].
When a pronunciation rule is specified more than once for a given string target in a given language, it MUST give precedence to the last occurrence of the rule in such a way that any previously-defined pronunciation rule gets overridden.
If it also supports SSML Attributes, it MUST let any pronunciation instructions provided via the ssml:ph
attribute take precedence in
cases where a grapheme
element [PRONUNCIATION-LEXICON] matches a text node of an element that carries
the ssml:ph
attribute [SSML].
Reading Systems MUST support the rendering of Fixed-Layout Documents [EPUB-33].
rendition:layout
PropertyThe default global value is reflowable
if no meta
element carrying this
property occurs in the metadata
section [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:
rendition:orientation
PropertyThe default global value is auto
if no meta
element carrying this
property occurs in the metadata
section.
Reading Systems that support multiple orientations SHOULD convey the
intended orientation to the user unless the given value is auto
. The means by which
the intent is conveyed is implementation specific.
rendition:spread
PropertyThe default global value is auto
if no meta
element carrying this
property occurs in the metadata
section.
The rendition:spread
property values have the following processing requirements:
Reading Systems MUST NOT incorporate spine items in a Synthetic Spread.
Reading Systems SHOULD render a Synthetic Spread for spine items only when the device is in landscape orientation.
Reading Systems SHOULD treat the value "portrait
"
as a synonym of "both
" and create spreads regardless of orientation.
Reading Systems SHOULD render a Synthetic Spread regardless of device orientation.
Reading Systems MAY use Synthetic Spreads in specific or all device orientations as part of a Content Display Area utilization optimization process.
rendition:page-spread-*
PropertiesThe rendition:page-spread-left
property indicates that the given spine item SHOULD be rendered in the left-hand slot in the spread, and
rendition:page-spread-right
that it SHOULD be rendered
in the right-hand slot. The rendition:page-spread-center
property indicates that
the synthetic spread mode SHOULD be overridden and a single viewport
rendered and positioned at the center of the screen.
The rendition:page-spread-left
, rendition:page-spread-right
, and
rendition:page-spread-center
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 take precedence over whatever value of the page-break-before
property [CSSSnapshot] has been set for an XHTML Content
Document.
The presence of rendition:page-spread-center
does not change the viewport
dimensions. It does not indicate that a viewport with the size of the whole spread has
to be created. This is important so that the scale factor stays consistent between
regular and center-spread pages.
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
[EPUB-33]) when
it lacks a rendition:page-spread-*
property value. If the reflowable spine item has
a rendition:page-spread-*
specification, it MUST be
honored (e.g., by inserting a blank page).
Similarly, 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
) when it lacks a
rendition:page-spread-*
property value. If the pre-paginated spine item has a
rendition:page-spread-*
specification, it MUST be
honored (e.g., by inserting a blank page).
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.
Reading Systems MUST use the width and height expressions as defined in Expressing in HTML [EPUB-33] to render XHTML Content Documents.
Reading Systems MUST clip XHTML content to the initial containing
block (ICB) dimensions declared in the viewport
meta
tag — content positioned outside of the initial containing block will not
be visible. 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.
Reading Systems MUST use the dimensions as defined in Expressing the ICB in SVG [EPUB-33] to render SVG Content Documents.
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.
Reading Systems MUST process the EPUB Container [EPUB-33].
It is not required that an application that processes OCF Containers 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, the rendering requirements for Reading Systems defined in this section can be ignored.
For relative IRI references, Reading Systems MUST determine the Base IRI [RFC3986] according to the relevant language specifications for the given file formats. For example, CSS defines how relative IRI references work in the context of CSS style sheets and property declarations [CSSSnapshot].
Unlike most language specifications, Reading Systems MUST use the Root Directory of the OCF
Abstract Container as the default Base IRI as the Base IRI for all files within the
META-INF
directory.
This specification does not specify how a Reading System that is unable to represent OCF File and Path Names would compensate for this incompatibility.
META-INF
Directorycontainer.xml
)A Reading System MUST, by
default, use the Package Document referenced from first rootfile
element 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.
Reading Systems MUST NOT fail when encountering configuration
files in the META-INF
directory not listed in Reserved Files
[EPUB-33].
Reading Systems MUST treat any OCF files that specify that the ZIP file is split across multiple storage media as being in error.
Reading Systems MUST treat any OCF Containers that use compression techniques other than Deflate as being in error.
Reading Systems MUST support the ZIP64 extensions defined as "Version 1".
Reading Systems MUST treat OCF ZIP Containers that use ZIP encryption features as being in error.
It is not a requirement that Reading Systems preserve information from an OCF ZIP Container through load and save operations that are not defined within 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).
The following constraints apply to specific fields in the OCF ZIP Container archive:
Reading Systems MUST treat version needed to
extract
field values other than 10
, 20
or
45
in the local file header table as being in error.
Reading Systems MUST treat compression
method
field values other than 0
or 8
in the local file header table as
being in error.
Reading Systems MUST treat OCF ZIP Containers with an
Archive decryption header
or an Archive extra data record
as
being in error.
Reading Systems MUST support deobfuscation of resources as defined in Resource Obfuscation [EPUB-33].
Reading Systems MAY support Media Overlays [EPUB-33].
If a Reading System does not support Media Overlays, it MUST ignore both the
media-overlay
attribute on Manifest
item
elements [EPUB-33]
and the manifest item
elements where the media-type
attribute value equals
application/smil+xml
.
When a Reading System loads a Package
Document, it MUST refer to the 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 MAY correspond to an element at the start or in the middle of a Media Overlay. When the Media Overlay Document has finished playing, the Reading System SHOULD load the next EPUB Content Document (as specified in the Package Document spine) and also load its corresponding Media Overlay Document, provided that one is given.
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 has finished playing. A par
element's
[EPUB-33] children MUST be rendered in parallel
(with each starting at the same time), and playback completes when all the children have
finished playing. When the body
element's last child has finished playing, playback
of the Media Overlay Document is done.
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 [EPUB-33] and ending at the clip offset time given by the clipEnd
attribute [EPUB-33]. The following rules MUST
be observed:
If clipBegin
is not specified, its value is assumed to be
"0
".
If clipEnd
is not specified, its value is assumed to be the full duration of
the physical media.
If clipEnd
exceeds the full duration of the physical media, then its value
is assumed to be the full duration of the physical media.
User-controllable audio playback options SHOULD include timescale modification, in which the playback rate is altered without distorting the pitch. The suggested range is half-speed to double-speed.
When presented with a Media Overlay text
element [EPUB-33], Reading Systems SHOULD ensure the EPUB Content Document element referenced by the
src
attribute is visible in the Viewport. 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 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.
An EPUB Content Document with which a Media Overlay is associated MAY itself contain embedded video and audio media, which MAY be pointed to by Media Overlay elements. Unlike text and images, video and audio media have an intrinsic duration. Consequently, when a Reading System renders the synchronization described by a Media Overlay, the default playback behavior of audio and video media embedded within the associated EPUB Content Document MUST be overridden.
Note that the rules below apply only to referenced [HTML] video
or audio
elements within the associated EPUB Content Document. That is to
say, the rules apply to only those elements pointed to by text
elements
[EPUB-33] within the Media Overlay (i.e., via the src
attribute). Embedded media that is not referenced by Media Overlay elements is not subject to
these rules.
All referenced audio and video media embedded within an EPUB Content Document MUST have their public playback interface deactivated (typically: play/pause control, time slider, volume level, etc.). This behavior is necessary to avoid interference between the scheduled playback sequence defined by the Media Overlay, and the arbitrary playback behavior due to user interaction or script execution. As a result, when the Reading System is in playback mode, it SHOULD:
Hide the individual video/audio UI controls from the page, which overrides the
default behavior defined by the [HTML] controls
attribute.
Prevent scripts embedded within the EPUB Content Document from invoking the JavaScript audio/video playback API (i.e., authored as part of the default behavior). It is RECOMMENDED that content producers avoid publishing embedded scripts dedicated to controlling the playback of embedded audio/video media. The published Media Overlay can then retain full control of the synchronized presentation without any risk of interference from script-enabled custom behaviors.
All referenced audio and video media embedded within an EPUB Content Document MUST be initialized to their "stopped" state, and be ready to
be played from the zero-position within their content stream (possibly displaying the
image specified using the [HTML] poster
attribute). This requirement overrides the default
behavior defined by the [HTML] autoplay
attribute.
When an EPUB Content Document element becomes active, the CSS Style Sheet visual
highlighting rules apply regardless of the content type referred to by that element's
src
attribute (e.g., the CSS class name defined by the active-class
metadata property [EPUB-33] SHOULD be applied to visible video and audio player controls within the host
EPUB Content Document).
In addition to the default behavior of Media Overlay activation for textual fragments and images, audio and video playback MUST be started and stopped according to the duration implied by the authored Media Overlay synchronization (as per the standard [SMIL3] timing model). There are two possible scenarios:
When a Media Overlay text
element has no audio
[EPUB-33] sibling within
its par
[EPUB-33] parent
container, the referenced EPUB Content Document audio or video media MUST play until it ends, at which point the
text
element's lifespan terminates. In this case, the implicit
duration of the text
element (and by inference, of the parent
par
container) is that of the referenced audio or video
clip.
When a Media Overlay text
element has an audio
sibling
within its par
parent container, the playback duration of the
referenced EPUB Content Document audio or video media MUST be constrained by the duration of the audio
sibling.
In this case, the actual duration of the parent par
container is
that of the child audio clip, regardless of the duration of the video or audio
media pointed to by the text
element. This behavior can result in
embedded video or audio media ending playback prematurely (before reaching its
full duration), or ending before the playback of the parallel Media Overlay
audio
is finished (in which case the last-played video frame
SHOULD remain visible until the parent
par
container finally ends). This behavior is equivalent of the
Media Overlay audio
element implicitly carrying the behavior of the
[SMIL3] endsync
attribute.
Furthermore, Reading Systems SHOULD expose user controls
for the volume levels of each independent audio track (i.e., from the
audio
element of the Media Overlay, and from the embedded audio
or video media within the EPUB Content Document), so that audio output can be
adjusted to match listeners' requirements. Note that having overlapping audio
tracks is typically an authoring-time concern: content producers usually add a
layer of audio information over a video track for description purposes. It is
RECOMMENDED that overlapping audio situations are
carefully examined and dealt with at production stage, as Reading Systems are
NOT REQUIRED to handle simultaneous volume levels
in any specific way.
When a text
element becomes inactive in the Media Overlay, and when it
points to embedded video or audio media, that referenced media MUST be reset to its initial "stopped" state, ready to be played from the
zero-position within their content stream (possibly displaying the poster image
specified using the [HTML] markup).
When a Media Overlay text
element [EPUB-33] with no audio
[EPUB-33] sibling element references text within the target EPUB Content Document,
Reading Systems capable of Text-to-Speech (TTS) SHOULD render the referenced text using
TTS.
As per Reading System conformance requirements, the speech-related information provided in the target EPUB Content Document SHOULD be used to play the audio stream as part of the Media Overlay rendering. (See SSML, Pronunciation Lexicons, and CSS3 Speech support requirements.)
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).
Reading Systems SHOULD use the semantic information provided by Media
Overlay elements' epub:type
attribute to
determine when to offer users the option of skippable features.
Reading Systems SHOULD allow escaping of nested structures. Reading
Systems MUST determine the start of nested structures by the value of
the epub:type
attribute and SHOULD offer users the option to skip playback of that structure and
resume with whatever content comes after it.
Reading Systems MAY support structural semantics [EPUB-33] in EPUB Content Documents.
A Reading System that supports structural semantics has to process the epub:type
attribute
as follows:
It MAY associate behaviors with none, some or all of the terms defined in the default vocabulary [EPUB-33].
It MAY associate behaviors with terms from other vocabularies.
It MUST ignore structural semantics that conflict with the carrying element.
When Reading System behavior associated with a given epub:type
value conflicts with an element's native behavior, the behavior associated with the element MUST be given precedence.
Reading Systems MUST support vocabulary association mechanisms [EPUB-33].
Reading Systems MUST resolve all reserved prefixes used in Package
Documents using their predefined URIs unless a local prefix is
declared. Reading Systems MUST use locally overridden prefixes in the
prefix
attribute when encountered.
As changes to the reserved prefixes and updates to Reading Systems are not always going happen in
synchrony, Reading Systems MUST NOT fail when encountering unrecognized
prefixes (i.e., not reserved and not declared using the prefix
attribute).
prefix
attributeIf the prefix
attribute includes a declaration for a predefined prefix, Reading Systems MUST use the URI mapping defined in the prefix
attribute,
regardless of whether of it maps to the same URI as the predefined prefix.
property
Data TypeA Reading System MUST use the following rules to create an IRI [RFC3987] from a property:
If the property consists only of a reference, the IRI is obtained by concatenating the IRI stem associated with the default vocabulary [EPUB-33] to the reference.
If the property consists of a prefix and reference, the IRI is obtained by concatenating the IRI stem associated with the prefix to the reference. If no matching prefix has been defined, the property is invalid and MUST be ignored.
The resulting IRI MUST be valid to [RFC3987]. Reading Systems do not have to resolve this IRI, however.
Reading Systems SHOULD process the general package rendering properties [EPUB-33].
rendition:flow
PropertyIf 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.
If a Reading Systems supports the rendition:layout
property, it
MUST ignore the rendition:flow
property when it has been
set on a spine item that also specifies the rendition:layout
value pre-paginated
.
The rendition:flow
property values have the following processing requirements:
The Reading System SHOULD dynamically paginate all overflow content.
The Reading System SHOULD render all Content Documents such that overflow content is scrollable, and the EPUB Publication SHOULD be presented as one continuous scroll from spine item to spine item (except where locally overridden [EPUB-33]).
The Reading System SHOULD render all Content Documents such that overflow content is scrollable, and each spine item SHOULD be presented as a separate scrollable document.
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 is 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 is vertical if the block flow direction is
downward (top-to-bottom). It is horizontal if the block flow direction of the root element is
rightward (left-to-right) or leftward (right-to-left).
rendition:align-x-center
PropertyWhen 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 version of this specification does not define a default rendering behavior when this property is not supported or specified. Reading Systems MAY render spine items by their own design.
Reading Systems MUST attempt to process an EPUB
Publication whose Package Document version
attribute is less than "3.0
".
EPUB Publications with older version numbers will not always render exactly as intended unless processed according to their respective specifications. Reading Systems SHOULD support such EPUB Publications as defined by those specifications.
Reading Systems SHOULD attempt to process an EPUB
Publication whose Package Document version
attribute is greater than
"3.0
".
Reading Systems SHOULD meet the accessibility requirements for Reading Systems in [EPUB-A11Y-10].
This section currently combines an overview of security and privacy considerations with issues previously cited in the specification.
The Working Group intends to develop this section throughout the revision to further expand on the issues and provide it with a more structured narrative.
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. This specification does not add any new features, APIs, etc. This also means that, essentially, the security and privacy issues are reliant on the features of those formats. In particular:
item
element
which allows both local and remote references). This is not unlike any external reference from an
average Web site that potentially exposes users to malicious content, and the general Web security
principles should be taken into account (e.g., cross-origin resource sharing).Additionally, the security considerations that apply to XML [XML] and
ZIP [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.
EPUB Creators and Reading System developers must be aware of the security issues that arise when scripted content is executed by a Reading System. As the underlying scripting model employed by Reading Systems and browsers is the same, the same kinds of issues encountered in Web contexts have to be taken into consideration.
Each Reading System has to establish if the scripts in a particular document are to be trusted or not. It is advised that all scripts be treated as untrusted (and potentially malicious), and that all vectors of attack be examined and protected against. In particular, the following need to be considered:
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 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).
The following recommendations are provided as a guide to handling untrusted scripts:
Reading Systems must behave as if a unique origin [URL] were allocated to each EPUB Publication. Adopting this approach will isolate publications from each other, thereby limiting access to cookies, DOM storage, etc.
Although domain isolation is the most effective way to secure EPUB Publications in Web-based Reading Systems, it is not always a realistic option. Web-based Reading Systems must still maintain isolation in such cases, which may require limiting access to scripting APIs that allow client-side data storage and access.
Reading Systems that enable scripting and network access should also include methods to notify the user that network activity is occurring and/or that allow them to disable it.
If a Reading System allows persistent data to be stored, that data must be treated as sensitive. Scripts may save persistent data through cookies and DOM storage but Reading Systems may block such attempts. Reading Systems that do allow data to be stored must ensure that it is not made available to other unrelated documents (e.g., ones that could have been spoofed). In particular, checking for a matching document identifier (or similar metadata) is not a valid method to control access to persistent data.
Reading Systems that allow local storage should also provide methods for users to inspect, disable, and delete that data. The data needs to be destroyed if the corresponding EPUB Publication is deleted.
Note that compliance with these recommendations does not guarantee protection from the possible attacks listed above; developers have to examine each potential vulnerability within the context of their Reading System.
Reading Systems need to 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 implementers need to 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 needs to be able to cancel the default action of any event, some events either might not be passed through or might not be cancelable.
This specification extends the [HTML] Navigator
object as follows.
WebIDL[Exposed=(Window)]
interface EpubReadingSystem
{
[LegacyUnforgeable] readonly attribute DOMString name
;
[LegacyUnforgeable] readonly attribute DOMString version
;
boolean hasFeature
(DOMString feature, optional DOMString version);
};
[WEBIDL] notation.
This specification does not define an epubReadingSystem
property extension for
the WorkerNavigator
object [WebWorkers]. 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.
The Navigator.epubReadingSystem
object
provides an interface through which a Scripted Content
Document can query information about a user's Reading System.
The object exposes properties of the Reading System (its name and
version), and provides the hasFeature
method which
can be invoked to determine the features it supports.
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 might create cloned instances of the
epubReadingSystem
object in Scripted Content Documents for technical
feasibility reasons. In such cases, the Reading System has to ensure that the object’s state
— as reflected by the values of its properties and methods — is consistently maintained
across all copied instances.
The following properties MUST be made available for retrieving information about the Reading System.
Name | Description |
---|---|
name
|
Returns a String value representing the name of the Reading System (e.g.,
"iBooks ", "Kindle "). |
version
|
Returns a String value representing the version of the Reading System
(e.g., "1.0 ", "2.1.1 "). |
layoutStyle
|
Use of the layoutStyle property is deprecated [EPUB-33]. Refer to its definition in [EPUBContentDocs-301] for usage
information. |
The hasFeature
method returns a boolean value indicating whether any version of the specified feature is
supported, or undefined
if the specified feature is not recognized.
The OPTIONAL
version
parameter is included for querying custom features that could change in
incompatible ways over time. The return value indicates support only for the specified
version of the feature.
EPUB Creators
SHOULD NOT include the version
parameter when querying
features defined in this specification —
these features are considered versionless. If a Reading System supports a feature defined in
this specification, it MUST ignore any supplied
version
parameter and return a true
value.
The following table lists the set of features that Reading Systems that support the
epubReadingSystem
object MUST recognize (i.e.,
provide a return value for). Support for these features is OPTIONAL.
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). |
Additional features MAY be added by Reading System developers, but future versions of this specification might append to this list in ways that could conflict or be incompatible with any such custom additions.
Note that this change log only identifies substantive changes — those that affect the conformance of Reading Systems or are similarly noteworthy.
For a list of all issues addressed during the revision, refer to the Working Group's issue tracker.
meta
element properties may define their own whitespace handling
rules. See issue 1295.dc:language
elements as the language of resources.dir
attribute
accounting for the addition of the new auto
value. See issue 1491.hreflang
attribute on
link
elements is not authoritative. See issue 1488.This section is non-normative.
The editors would like to thank the members of the EPUB 3 Working Group for their contributions to this specification: