W3C Candidate Recommendation Draft
Copyright © 1999-2022 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. 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 Candidate Recommendation Draft using the Recommendation track.
Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates changes from the previous Candidate Recommendation that the Working Group intends to include in a subsequent Candidate Recommendation Snapshot.
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 2 November 2021 W3C Process Document.
This section is non-normative.
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. 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.
This specification uses terminology defined in EPUB 3.3 [epub-33].
It also defines the following term:
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.
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, 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 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, 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 must keep track of changes to the SVG standard to ensure that they keep their systems up to date.
Whether a reading system has to support a feature is mentioned at the beginning of its section. To be conformant with this specification, reading systems MUST support all required features as well as all applicable conditionally-required features (e.g., to support image rendering if the reading system has a viewport) as defined in their respective sections.
When supporting recommended and optional features, reading systems MUST meet all normative requirements as defined in their respective sections.
When reading system developers opt not to support a recommended or optional feature, it does not always mean none of the normative requirements of the section apply. In some cases, there may be alternative requirements when not implementing a feature (e.g., to process fallbacks when scripting is not supported). Reading systems MUST meet these alternative requirements when not supporting a feature.
EPUB publications frequently contain information not required by this specification (e.g., package document metadata). Reading systems may use this additional information for any purposes (e.g., to improve the user interface).
Reading systems MUST process publication resources [epub-33].
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.
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].
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 [rfc7230].
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.
Reading Systems MUST prevent access to resources referenced via file URLs [rfc8089].
A reading system MUST be both of the following:
a conformant processor as defined in [xml-names].
In addition, when processing XML documents, a reading system MUST NOT resolve external identifiers in DOCTYPE, ENTITY and NOTATION declarations [xml].
A reading system MUST process, for all publication resources, the attributes that set the language for the documents' contents, when applicable. This includes:
xml:lang
attribute
[xml] for all XML documents (e.g., the package document, XHTML content documents,
SVG content documents, and media overlay documents).lang
attribute for XHTML content documents and SVG
content documents. (Refer to respective "The 'lang' and 'xml:lang' attributes" sections in
[html] and [svg] for more information.)Similarly, a reading system MUST process, for all publication resources, the attributes that set the base direction for the documents' contents, when applicable. This includes:
dir
attribute [epub-33] for the
package document. (See also 5.1 Base direction for further details.)dir
attribute for XHTML content
documents.direction
attribute for SVG content documents.In the absence of this information in a publication resource, reading systems MUST NOT assume
either the 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.
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 15. Security and privacy.
If reading system developers allow network access, it is RECOMMENDED both that they:
Reading systems SHOULD open links that resolve outside the EPUB publication in a new browser instance to ensure that the browser's security and privacy controls are available to users.
Although links to external web sites and resources are commonly found in EPUB content documents, these are not the only sources. For example, if a reading system provides access to linked records [epub-33] in the package document metadata, it should similarly open the links in a new browser instance.
For more information about security and privacy issues with external links, see 15.2 Threat model.
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.
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:
/
" with the container root
URL as base is the container
root URL...
" with the container root
URL as base is the container
root URL.The unicity of the origin 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].
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.
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.xml
)Reading systems SHOULD ignore metadata.xml
files [epub-33] with unrecognized root
elements.
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.
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.
Reading systems MUST NOT fail when encountering configuration files in the META-INF
directory not listed in Reserved files [epub-33].
A reading system:
MUST treat any OCF containers that specify the [zip] file is split across multiple storage media as in error.
MUST treat any OCF containers that use compression techniques other than Deflate [rfc1951] as in error.
MUST support the ZIP64 extensions defined as "Version 1" [zip].
MUST treat OCF ZIP containers that use [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.
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.
Reading systems MUST process the package document [epub-33].
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].
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.
Reading systems MUST strip and collapse ASCII whitespace [infra] from Dublin Core [dcterms] and meta
element values
[epub-33] before processing.
dc:identifier
elementTo 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].
dc:title
elementReading 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.
dc:language
elementThe language(s) of the EPUB publication specified in dc:language
elements are
informational. Some uses of this information include:
See 3.7 Internationalization for more details on how to determine the language of a publication resource.
dc:creator
elementWhen 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).
meta
elementReading 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 the property
attribute's value does not
include a prefix [epub-33], reading
systems MUST use the prefix URL "http://idpf.org/epub/vocab/package/meta/#
" to
expand the value.
If a reading system does not recognize the scheme
attribute [epub-33] value, it SHOULD treat the value of
the element as a string.
link
elementRetrieval and support of linked resources is OPTIONAL.
The language identified in an hreflang
attribute is purely
advisory. Upon fetching the resource, a reading system MUST use the language information
associated with the resource to determine its language, not the metadata included in the
link to the resource.
In the case of a linked metadata record [epub-33], reading systems MUST NOT skip processing the metadata expressed in the package document (i.e., use only the information expressed in the record). Reading systems MAY compile metadata from multiple linked records.
When 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 [epub-33] in the
package document to establish precedence (i.e., metadata in the first linked record 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.
If any of the rel
or properties
[epub-33] attributes' values do not include a prefix, reading systems MUST use the prefix
URL "http://idpf.org/epub/vocab/package/link/#
" to expand the values.
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's preferred fallback order.
If a reading system does not support any resource
in the fallback chain, it MUST alert the reader 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.
If any of the properties
attribute's values do not
include a prefix [epub-33], reading systems MUST
use the prefix URL "http://idpf.org/epub/vocab/package/item/#
" to expand the values.
Reading systems MUST provide a means of
rendering the EPUB publication in the order defined in the spine
element [epub-33], which
includes:
itemref
[epub-33] as the beginning of the default reading order;
and,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.
If any values of the properties
attribute do not include a prefix [epub-33], reading systems MUST use the
prefix URL "http://idpf.org/epub/vocab/package/itemref/#
" to expand the values.
Reading systems MUST ignore all
values expressed in spine itemref
properties
attributes that they do not recognize.
Reading systems MUST NOT skip spine references to duplicate manifest items 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.
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.
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.
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.
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 10. Processing structural semantics, a reading system MUST ignore semantics expressed
on the [html] head
element or its descendants.
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 [html].
Use of the switch
element is deprecated
[epub-33]. Refer to its definition in [epubcontentdocs-301] for implementation
information.
Use of the trigger
element is deprecated
[epub-33]. Refer to its definition in [epubcontentdocs-301] for implementation
information.
Reading systems MAY support custom attributes provided the attributes do not modify the requirements of this specification.
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.
Reading systems MUST process SVG embedded in XHTML content documents as defined in 6.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].
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 6.4 Scripting.
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 6.1.2.2.1 Embedded SVG and 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].
MUST 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, the
getOverrideStyle
method [dom-level-2-style], or [html]
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.
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].
That origin [url] 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, 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 extend the navigator object [html]
with the epubReadingSystem
interface defined in 16. epubReadingSystem object. It also MUST support the
dom-manipulation
and layout-change
features defined in 16.4.1.2 Features 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].
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.
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.
This section is non-normative.
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 [url] allocated to each EPUB publication (see 4.1.1 URL of the root directory). 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 6.4 Scripting).
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.
Reading systems MUST support the rendering of fixed-layout documents [epub-33].
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:
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:
The reading system determines the orientation in which to render the content.
Reading systems that support multiple orientations SHOULD render the content in landscape orientation.
Reading systems that support multiple orientations SHOULD render the content in portrait orientation.
The means by which they convey the intent is implementation specific.
The default
value auto
MUST be assumed by EPUB reading systems 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:
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.
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.
The rendition:page-spread-left
property [epub-33] indicates that the given spine item SHOULD be rendered in
the left-hand slot in the spread.
The rendition:page-spread-right
property [epub-33] indicates that the given spine item SHOULD be rendered in
the right-hand slot in the 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.
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
attribute) 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 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.
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 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 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 SHOULD process the reflowable layout properties [epub-33].
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:
The reading system SHOULD dynamically paginate all overflow content.
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]).
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.
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].
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.
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].
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:
media-overlay
attribute on
manifest item
elements [epub-33]; anditem
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 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 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 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.
When presented with a media overlay audio
element, 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.
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.
An EPUB content document with which a media overlay is associated MAY itself contain embedded video and audio media. The media overlay elements MAY point to these 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, it MUST override the default playback behavior of audio and video media embedded within the associated EPUB content document.
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). These rules do not apply to
embedded media not referenced by media overlay elements.
Reading systems MUST deactivate the public playback interface for all referenced audio and video media embedded within an EPUB content document (typically: play/pause control, time slider, volume level, etc.). This behavior avoids 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:
Reading systems MUST initialize all referenced audio and video media embedded within an
EPUB content document to their "stopped" state, and ready them to play 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, reading systems MUST constrain the
playback duration of the referenced EPUB content document audio or video media
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 users can adjust the audio output to match their
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. Reading systems
handling of simultaneous volume levels in any specific way is OPTIONAL.
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) 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.
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.
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.
Reading systems MAY support structural semantics [epub-33] in EPUB content documents.
When processing the epub:type
attribute, a reading system:
MAY associate behaviors with none, some, or all of the terms defined in the default vocabulary [epub-33].
MAY associate behaviors with terms from other vocabularies.
MUST ignore terms that it does not recognize.
Reading systems MUST support vocabulary association mechanisms [epub-33].
Reading systems MUST resolve all reserved prefixes [epub-33] used in
package documents using their predefined URLs unless the EPUB creator declares a local prefix.
Reading systems MUST use the URLs defined for locally
overridden prefixes (using 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
URL mapping defined in the prefix
attribute, regardless of whether of it maps to
the same URL as the predefined prefix.
property
Data TypesReading systems MUST expand property
values [epub-33] as follows:
If the property consists only of a reference, concatenate the prefix URL associated with the default vocabulary [epub-33] to the reference.
If the property consists of a prefix and reference, concatenate the URL defined for the prefix to the reference. If the EPUB creator has not defined a matching prefix, and it is not a reserved prefix [epub-33], the property is invalid and reading systems MUST ignore it.
If the property consists only of a prefix (i.e., there is no reference after the colon), the property is invalid and reading systems MUST ignore it.
If the process does not result in a valid URL string, reading systems MUST ignore the property.
Reading systems do not have to parse the resulting URL [url] or attempt to dereference the resource.
Reading systems MUST attempt to process
an EPUB publication whose package document version
attribute [epub-33] 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
[epub-33] is greater than "3.0
".
This section is non-normative.
Although the primary focus of this specification is on how to process and render EPUB publications it does not mandate specific user interfaces that all reading systems must offer. This does not mean that there are not common accessibility issues that all reading systems developers should be aware of, or seek to avoid in their applications.
The W3C's User Agent Accessibility Guidelines [uaag20] provides many useful practices developers should apply to improve their reading systems as many browser accessibility issues have parallels in EPUB-specific user agents.
The following list outlines some additional EPUB-specific areas where a lack of accessibility impacts the reading experience for users:
The DAISY Consortium maintains an accessibility test suite to aid in evaluating these issues and more.
This section is non-normative.
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].
This section is non-normative.
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.
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 6.4.3 Security considerations.
EPUB publications may contain resources designed to exploit security flaws in reading systems or the operating systems they run on.
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 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
.
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 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 6.4.3 Security considerations.
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.
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.
Reading systems that allow users to load untrustworthy EPUB publications (e.g., unsigned EPUB publications through the process of "sideloading") SHOULD treat such content as insecure (e.g., prompt users to allow scripting and network access).
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.
This specification extends the Navigator
object [html] as follows.
WebIDL[Exposed=(Window)]
interface EpubReadingSystem
{
[LegacyUnforgeable] readonly attribute DOMString name
;
[LegacyUnforgeable] readonly attribute DOMString version
;
boolean hasFeature
(DOMString feature, optional DOMString version);
};
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.
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 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.
The reading system MUST make the following properties available for retrieving information about it.
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 "). |
This specification used to define a layoutStyle
property, but it is now deprecated [epub-33]. Refer to its definition in
[epubcontentdocs-301] for more information.
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.
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.
EpubReadingSystem
interface
§16.1hasFeature
method for EpubReadingSystem
§16.4.1.1name
attribute for EpubReadingSystem
§16.3Navigator.epubReadingSystem
attribute for Navigator
§16.2version
attribute for EpubReadingSystem
§16.3dc:creator
element
dc:identifier
element
dc:language
element
dc:title
element
epub:type
attribute
item
element
itemref
element
link
element
meta
element
spine
element
text
element
audio
element
autoplay
attribute (for audio
element)
controls
attribute (for audio
element)
dir
attribute (for html-global
element)
head
element
object
type
poster
attribute (for video
element)
style
attribute (for html-global
element)
video
element
boolean
type
DOMString
interface
[Exposed]
extended attribute
[LegacyUnforgeable]
extended attribute
[SameObject]
extended attribute
This section is non-normative.
Note that this change log only identifies substantive Changes since EPUB 3.2 — 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.
rendition:spread
and
rendition:orientation
properties to requirements, to align with
rendition:layout
. See issue 1936.page-spread-center
is now an alias for spread-none
. See
issue 1929.textref
attributes and the text
element's
src
attribute. Support for other fragment identifier schemes is optional. See
issue 1586.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.
Specifications, like art, are human creations. No human has done more for EPUB than Garth Conboy, who has been there every step of the way, from the very first OEB 1.0 in 1999 to today's EPUB 3.3. None of this would have happened without Garth's vision, knowledge, and preternatural good nature. We dedicate EPUB 3.3 to his memory. We are forever in your debt, Garth.
The following members of the EPUB 3 Working Group contributed to the development of this specification:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: