1. Overview
1.1 Purpose and Scope
This section is non-normative.
This specification, EPUB Content Documents 3.1, defines profiles of HTML, SVG, and CSS for use in the context ofEPUB® Publications.
This specification is one of afamily of specifications that compose[EPUB 3.1], an interchange and delivery format for digital publications based on XML and Web Standards. It is meant to be read and understood in concert with the other specifications that make up EPUB 3.1.
Refer to[EPUB3 Changes] for more information on the differences between this specification and its predecessor.
1.2 Relationship to Other Specifications
This section is non-normative.
1.2.2 Relationship to SVG
This specification does not reference a specific version of[SVG], but instead uses an undated reference that will always point to the latest recommendation. This approach ensures that EPUB will always keep pace with changes to the SVG standard. Authors and Reading System developers will need to keep track of changes to the SVG standard, and ensure that their processes and systems are kept up to date.
1.3 Terminology
Terms with meanings specific to EPUB 3.1 are capitalized in this document (e.g., "Author", "Reading System"). A complete list of theseterms and definitions is provided in[EPUB 3.1].
Only the first instance of a term in a section is linked to its definition.
1.4 Conformance Statements
The keywordsMUST,MUST NOT,REQUIRED,SHALL,SHALL NOT,SHOULD,SHOULD NOT,RECOMMENDED,MAY, andOPTIONAL in this document are to be interpreted as described in[RFC2119].
All sections and appendixes of this specification are normative except where identified by the informative status label "This section is informative". The application of informative status to sections and appendixes applies to all child content and subsections they contain.
All examples in this specification are informative.
1.5 Namespace prefix mapping
For convenience, the following namespace prefixes[XMLNS] are used in this specification without explicitly being declared. To use any of these prefixes in anEPUB Content Document, a declaration isREQUIRED.
| prefix | URI |
|---|
epub | http://www.idpf.org/2007/ops |
pls | https://www.w3.org/2005/01/pronunciation-lexicon |
ssml | https://www.w3.org/2001/10/synthesis |
2. XHTML Content Documents
2.1 Introduction
This section defines a profile of[HTML] for creating XHTML Content Documents. An instance of an XML document that conforms to this profile is aCore Media Type Resource and is referred to in this specification as anXHTML Content Document.
Unless otherwise specified, this specification inherits all definitions of semantics, structure and processing behaviors from the[HTML] specification.
2.2 Content Conformance
AnXHTML Content DocumentMUST meet all of the following criteria:
- Document Properties
ItMUST be an[HTML] document that conforms to theXHTML syntax.
ItMUST meet the conformance constraints for XML documents defined inXML Conformance[EPUB 3.1].
For all document constructs used that are defined by[HTML], itMUST conform to the conformance criteria defined for those constructs in that specification, unless explicitly overridden inHTML Deviations and Constraints.
ItMAY include extensions to the[HTML] grammar as defined inHTML Extensions, andMUST conform to all content conformance constraints defined therein.
- File Properties
The XHTML Content Document filenameSHOULD use the file extension.xhtml
2.4 HTML Extensions
This section defines EPUB 3.1XHTML Content Document extensions to the underlying[HTML] document model.
Note
Although[HTML] allows user agents to supportvendor-neutral extensions, unless such extensions are listed in this section they are not supported features of EPUB 3.1.
2.4.1 Semantic Inflection
2.4.1.1 Introduction
This section is non-normative.
Semantic inflection is the process of attaching additional meaning about the specific purpose and/or nature an element plays in anXHTML Content Document. Theepub:type attribute is used to express domain-specific semantics in XHTML Content Documents, with the inflection(s) it carries complementing the underlying[HTML] vocabulary.
The applied semantics are intended to refine the meaning of their containing elements; they are not provided to override their nature (e.g., the attribute can be used to indicate asection is a chapter in a work, but is not designed to turnp elements into list items to avoid proper list structures).
Semantic metadata is not intended for direct human consumption; it instead provides a controlled way for Reading Systems to learn more about the structure and content of a document, providing them the opportunity to enhance the reading experience for users.
This specification defines a method for semantic inflection usingthe attribute axis: instead of adding new elements, theepub:type attribute can be appended to existing elements to inflect the desired semantics. A mechanism to identify external vocabularies that provide controlled values for the attributes is also defined.
2.4.1.2 The epub:type Attribute
Theepub:type attribute inflects semantics on the element on which it appears. Its value is one or more white space-separated terms stemming from external vocabularies associated with the document instance, as defined inVocabulary Association.
The inflected semanticMUST express a subclass of the semantic of the carrying element. In the case of semantically neutral elements, such as the[HTML]div andspan elements, the inflected semanticMUST NOT attach a meaning that is already conveyed by an existing element (e.g., that adiv represents a paragraph or section). Reading SystemsMUSTignore inflected semantics that conflict with the carrying element.
As the[HTML]head element contains metadata for the document, structural semantics expressed on this element or any descendant of it have no meaning. Reading SystemsMUST ignore such semantics.
Examples
The following example shows how a preamble could be marked up with theepub:type attribute on its containing[HTML]section element.
<html …xmlns:epub="http://www.idpf.org/2007/ops"> …<sectionepub:type="preamble"> …</section> …</html>
The following example shows theepub:type attribute used to add glossary semantics on an[HTML] definition list.
<html …xmlns:epub="http://www.idpf.org/2007/ops"> …<dlepub:type="glossary"> …</dl> …</html>
The following example shows theepub:type attribute used to add pagebreak semantics.
<html …xmlns:epub="http://www.idpf.org/2007/ops"> …<p> …<spanepub:type="pagebreak"title="234"id="p234"/> …</p> …</html>
2.4.1.3 Vocabulary Association
This specification adopts the vocabulary association mechanisms defined inVocabulary Association Mechanisms[Packages 3.1], with the following modifications:
Default Vocabulary
The default vocabulary for Content Documents is defined to be theEPUB 3 Structural Semantics Vocabulary.
Reserved Prefixes
The reserved prefixes that AuthorsMAY use in theepub:type attribute without having to declare are defined in[Reserved Prefixes].
The prefix Attribute
Theprefix attribute definition is unchanged, but the attribute is defined to be in the namespacehttp://www.idpf.org/2007/ops when used in EPUB Content Documents.
Theprefix attribute is only valid on the[HTML] roothtml element.
2.4.1.4 Processing Requirements
A Reading SystemMUST process theepub:type attribute as follows:
ItMAY associate behaviors with none, some or all of the terms defined in thedefault vocabulary.
ItMAY associate behaviors with terms from other vocabularies.
ItMUST ignore terms that it does not recognize.
When Reading System behavior associated with a givenepub:type value conflicts with an element's native behavior, the behavior associated with the elementMUST be given precedence.
2.4.2 Semantic Enrichment
2.4.2.1 Introduction
This section is non-normative.
Unlikesemantic inflection, which is about refining the structures within the markup, semantic enrichment enables the layering of meaning into the content in order to facilitate machine processing.
The[Microdata] and[RDFa 1.1] specifications both define sets of attributes that can be used inXHTML Content Documents to semantically enrich the content.
2.4.3 SSML Attributes
2.4.3.1 Introduction
TheW3C Speech Synthesis Markup Language[SSML] is a language used for assistingText-to-Speech (TTS) engines in generating synthetic speech. Although SSML is designed as a standalone document type, it also defines semantics suitable for use within other markup languages.
This specification recasts the[SSML]phoneme element as two attributes —ssml:ph andssml:alphabet — and makes them available within XHTML Content Documents.
Reading Systems withText-to-Speech (TTS) capabilitiesSHOULD support the SSML Attributes as defined below.
2.4.3.2 The ssml:ph attribute
Thessml:ph attribute specifies a phonemic/phonetic pronunciation of the text represented by the element to which the attribute is attached.
- Attribute Name
ph
- Namespace
https://www.w3.org/2001/10/synthesis
- Usage
Global attribute.MAY be specified on all elements with which a phonetic equivalent can logically be associated (e.g., elements that contain textual information).
MUST NOT be specified on a descendant of an element that already carries this attribute.
- Value
A phonemic/phonetic expression, syntactically valid with respect tothe phonemic/phonetic alphabet being used.
This attribute inherits all the semantics of the[SSML]phoneme elementph attribute, with the following addition:
When thessml:ph attribute appears on an element that has text node descendants, the corresponding document text to which the pronunciation applies is the string that results from concatenating the descendant text nodes, in document order. The specified phonetic pronunciationMUST therefore logically match the element's textual data in its entirety (i.e., not just an isolated part of its content).
Reading Systems that support the SSML Attributes andPLS DocumentsMUST honor the definedprecedence rules for these two constructs.
2.4.3.3 The ssml:alphabet attribute
Thessml:alphabet attribute specifies which phonemic/phonetic pronunciation alphabet is used in the value of thessml:ph attribute.
- Attribute Name
alphabet
- Namespace
https://www.w3.org/2001/10/synthesis
- Usage
Global attribute.MAY be specified on any element.
- Value
The name of the pronunciation alphabet used in the value ofssml:ph (inherited).
This attribute inherits all the semantics of the[SSML]phoneme elementalphabet attribute, with the following addition:
The value of thessml:alphabet attribute is inherited in the document tree. The pronunciation alphabet used in a givenssml:ph attribute value is determined by locating the first occurrence of thessml:alphabet attribute starting with the element on which thessml:ph attribute appears, followed by the nearest ancestor element.
Reading Systems that support theSSML Attributes feature of this specificationSHOULD support the IPA alphabet[IPA], as expressed by the value "ipa".
2.4.4 Alternate Style Tags
In accordance with[Alt Style Tags] , thelink elementclass attributeMAY include any of the following values:horizontal,vertical,day andnight. These values inherit the semantics defined by that specification for their use.
Reading SystemsSHOULD select and utilize such tagged style sets as appropriate, and as described in that specification.
2.4.5 Custom Attributes
Reading SystemsMAY introduce functionality not defined in this specification to enhance the rendering ofEPUB Publications. To facilitate this experimentation, vendorsMAY define custom attributes for use inXHTML Content Documents.
Custom attributesMAY be included on any element in an XHTML Content Document provided such attributes are from a foreign namespace, which is defined as a namespace[XMLNS] that does not map to either of the following URIs:
Custom attributes, and the behaviors associated with them,MUST NOT alter the integrity of an EPUB Publication. The contentMUST remain consumable by a user without any information loss or other significant deterioration, regardless of the Reading System it is rendered on.
Note
To facilitate interoperability of custom attributes across Reading Systems, vendors are strongly encouraged to document any extensions they implement in[Attribute Extensions].
2.5 HTML Deviations and Constraints
This section defines deviations from, and constraints on, the underlying[HTML] document model applicable to EPUB 3.1XHTML Content Documents.
2.5.1 Embedded MathML
2.5.1.1 Introduction
This section is non-normative.
XHTML Content Documents support embedded[MATHML] but limit its usage to a restricted subset of the full MathML markup language.
This subset is designed to ease the implementation burden on Reading Systems and to promote accessibility, while retaining compatibility with[HTML] user agents.
2.5.1.2 Content Conformance
Any occurrence of MathML markup in XHTML Content DocumentsMUST conform to the constraints expressed in the MathML specification[MATHML], with the following additional restrictions:
- Presentation MathML
Themath elementMUST contain onlyPresentation MathML, with the exception of theannotation-xml element as defined below.
- Content MathML
Content MathMLMAY be included within MathML markup in XHTML Content Documents, and, when present,MUST occur within anannotation-xml child element of ansemantics element.
When Content MathML is included as per the previous condition, the givenannotation-xml element'sencoding attributeMUST be set to either of the functionally-equivalent valuesMathML-Content orapplication/mathml-content+xml, and itsname attributeMUST be set tocontentequiv.
- Deprecated MathML
Elements and attributes marked as deprecated in[MATHML]MUST NOT be included within MathML markup in XHTML Content Documents.
- XHTML Content Document fragments
XHTML Content Document fragmentsMAY be included within MathML markup in XHTML Content Documents, and, when present,MUST occur within anannotation-xml child element of ansemantics element.
When an XHTML Content Document fragment is included as per the above paragraph, the givenannotation-xml element'sencoding attributeMUST be set toapplication/xhtml+xml and itsname attributeMUST be set toalternate-representation.
Any included XHTML Content Document fragmentsMUST NOT themselves contain MathML markup.
Any included XHTML Content Document fragmentsMUST conform to the content model in which the ancestormath element occurs, such that if themath element is replaced by the given XHTML Content Document fragment the document remains valid.
2.5.1.3 Reading System Conformance
A conformantEPUB Reading SystemMUST meet all of the following criteria for processing MathML embedded in XHTML Content Documents:
2.5.1.4 Fallback Content
As Reading System support for MathML rendering is inconsistent,Authors are encouraged to provide a fallback image using thealtimg attribute on themath element. It isRECOMMENDED that the dimension and alignment attributes (altimg-width,altimg-height andaltimg-valign) be used in conjunction with thealtimg attribute.
2.5.2 Embedded SVG
XHTML Content Documents support the embedding ofSVG document fragmentsby reference (embedding via reference, for example, from animg orobject element) andby inclusion (embedding via direct inclusion of thesvg element in the XHTML Content Document)[SVG].
The content conformance constraints for SVG embedded in XHTML Content Documents are the same as defined forSVG Content Documents inRestrictions on SVG.
Reading SystemsMUST process SVG embedded in XHTML Content Documents as defined inSVG Content Documents — Reading System Conformance.
2.5.2.1 Embedded SVG and CSS
For the purposes of styling SVG embedded in XHTML Content Documentsby reference, Reading SystemsMUST NOT apply CSS style rules of the containing document to the referenced SVG document.
For the purposes of styling SVG embedded in XHTML Content Documentsby inclusion, Reading SystemsMUST apply applicable CSS rules of the containing document to the included SVG elements.
Note
SVG includedby reference is processed as a separate document, and can include its own CSS style rules just like anSVG Content Document would. Note that this is consistent with situations where an[HTML]object element references an external[HTML] element.
2.5.3 Unicode Restrictions
This section lists restrictions on the Unicode character repertoire.
- Private Use Characters and Embedded Fonts
Any included characters that map to a code point within one of the Private Use Area (PUA) ranges as defined in[Unicode]MUST occur within a string that is styled or attributed in a manner that includes a reference to an embedded font[CSS3 Fonts] that contains an appropriate glyph for that code point.
2.5.4 Discouraged Constructs
This section is non-normative.
2.5.4.1 The rp Element
The[HTML]rp element is intended to provide a fallback for older versionReading Systems that do not recognize ruby markup (i.e., a parenthesis display aroundruby markup). As EPUB 3.1 Reading Systems are ruby-aware, and can provide fallbacks, the use ofrp elements is discouraged.
2.5.4.2 The embed Element
Since the[HTML]embed element does not include intrinsic facilities to providefallbacks for Reading Systems that do not support scripting,Authors are discouraged from using the element when the referenced resource includes scripting. Theobject element can be used instead, as it includes intrinsic fallback capabilities.
2.5.5 Foreign Resource Restrictions
Foreign ResourcesMAY be referenced from elements that have intrinsic fallback mechanisms, where an intrinsic fallback method is the capability to offer an alternative presentation if the foreign resource is not supported. For example, most[HTML]embedded content elements provide options for alternative rendering, such as allowing multiple sources to be specified or allowing embedded HTML content for when a resource cannot be rendered. ACore Media Type Resource or embedded HTML contentMUST be provided via the given element's intrinsic fallback mechanism when a Foreign Resource is referenced.
Flow contentMAY be embedded within the[HTML]audio andvideo elements for rendering in older Reading Systems that do not recognize these elements (e.g., EPUB 2 Reading Systems), but it does not represent a Core Media Type fallback.
The following[HTML] elements are exempt fromCore Media Type requirements[EPUB 3.1]:
Foreign ResourcesMAY be referenced from the above elements without the provision of a Core Media Type fallback.
3. SVG Content Documents
Caution
Some features of[SVG] are not fully supported inReading Systems, or supported across all platforms on which Reading Systems run. When utilizing such features,Authors need to consider the inherent risks in terms of the potential impact on interoperability and document longevity.
3.1 Introduction
This section is non-normative.
The Scalable Vector Graphics (SVG) specification[SVG] defines a format for representing final-form vector graphics and text.
Although an EPUB Publication typically usesXHTML Content Documents as thetop-level document type, the use ofSVG Content Documents is also permitted. SVGs are typically only used in certain special circumstances, such as when final-form page images are the only suitable representation of the content (e.g., in the context of manga or comic books).
This section defines a profile for[SVG] documents. An instance of an XML document that conforms to this profile is aCore Media Type Resource and is referred to in this specification as anSVG Content Document.
Note
This section defines conformance requirements forSVG Content Documents. Refer toEmbedded SVG for conformance requirements for SVG embedded in XHTML Content Documents.
3.4 Reading System Conformance
A conformantEPUB Reading SystemMUST meet all of the following criteria for processing SVG Content Documents and SVGembedded in XHTML Content Documents:
Unless explicitly defined by this specification as overridden, itMUST process SVG Content Documents using semantics defined by the[SVG] specification and honor any applicable user agent conformance constraints expressed therein.
ItMUST meet the Reading System conformance criteria defined inScripted Content Documents — Reading System Conformance.
If it has aViewport, itMUST support the visual rendering of SVG using CSS as defined inStyling[SVG], and itSHOULD support all properties defined inProperty Index[SVG]. In the case of embedded SVG, itMUST also conform to the constraints defined inEmbedded SVG and CSS.
ItSHOULD support user selection and searching of text within SVG elements.
ItMUST recognize the value "http://www.idpf.org/2007/ops" of therequiredExtensions attribute as representing the occurrence of XHTML Content Document fragments (e.g., when the attribute is included on theforeignObject element or children of theswitch element).
4. CSS Style Sheets
4.1 Introduction
This section is non-normative.
CSS has been an integral part of the Open Web Platform for nearly two decades — readers, publishers, and document authors expect CSS to "just work," as they expect HTML to just work.
In the past, EPUB defined a profile of CSS that mandated support for certain properties and provided prefixed versions of numerous other properties. Although the CSS Working Group no longer recommends the use of prefixed properties, this specification has to maintain some prefixed properties to avoid breaking existing content. But with the minor exceptions defined in this section, EPUB defers to theW3C to define CSS.
A conformant CSS style sheetMUST meet all of the following criteria:
Note
Keep in mind that someReading Systems will not support all desired features of CSS. In particular, the following are known to be problematic:
Reading System-induced pagination can interact poorly with style sheets. Pagination is sometimes done using columns, which can result in incorrect values for viewport sizes. Fixed and absolute positioning are particularly problematic.
Some types of screens will render animations and transitions poorly (e.g., those with high latency).
4.3 Reading System Conformance
A conformantEPUB Reading SystemMUST meet all of the following criteria for processing CSS Style Sheets:
Reading System developers are encouraged to implement CSS support at the level of major browsers.
4.4 Prefixed Properties
Caution
Authors are strongly encouraged to use unprefixed properties, andReading Systems to support current CSS specifications. The widely-used prefixed properties from[Content Docs 3.0.1] have been retained, but support for the other properties has been removed. Authors are advised to use CSS-native solutions for the removed properties where and when they are available.
Authors currently using these prefixed properties are advised to move to unprefixed versions as soon as support allows, as these properties are not anticipated to be supported in the next major version of EPUB.
4.4.1 CSS Writing Modes
The following table lists the-epub- prefixed properties for[CSS3 Writing Modes]. The Value column indicates the value the property accepts. The Prior EPUB Mapping column indicates values/properties that were used in previous versions of EPUB 3. An asterisk (*) denotes that the older property or value is now deprecated. The final column describes how to implement the prefixed property based on[CSS3 Writing Modes-20151215].
| Property | Value | Prior EPUB Mapping | Mapping to[CSS3 Writing Modes-20151215] |
|---|
| -epub-text-orientation | upright | upright | upright |
| -epub-text-orientation | mixed | vertical-right* | mixed |
| -epub-text-orientation | sideways-right | sideways-right | sideways |
| -epub-text-orientation | sideways-right | rotate-right* | sideways |
| -epub-text-orientation | sideways | rotate-normal* | sideways |
| -epub-text-orientation | sideways | sideways | sideways |
| -epub-text-orientation | mixed | mixed | mixed |
| -epub-writing-mode | horizontal-tb | horizontal-tb | horizontal-tb |
| -epub-writing-mode | vertical-rl | vertical-rl | vertical-rl |
| -epub-writing-mode | vertical-lr | vertical-lr | vertical-lr |
| -epub-text-combine* | -epub-text-combine-horizontal: none | none | text-combine-upright: none |
| -epub-text-combine* | -epub-text-combine-horizontal: all | horizontal | text-combine-upright: all |
| -epub-text-combine* | Error | horizontal <number> | text-combine-upright: digits <number> |
4.4.2 CSS Text Level 3
| Property | Value | Mapping to[CSS3 Text-20160119] |
|---|
| -epub-hyphens | none | manual | auto | No Change |
| -epub-hyphens | all | Not Supported |
| -epub-line-break | auto | loose | normal | strict | No Change |
| -epub-text-align-last | auto | start | end | left | right | center | justify | No Change |
| -epub-word-break | normal | keep-all | break-all | No Change |
| text-transform | -epub-fullwidth | text-transform: full-width |
4.4.3 CSS Text Decoration Level 3
| Property | Value | Mapping to[CSS3 Text Decoration] |
|---|
| -epub-text-emphasis-color | <color> | No Change |
| -epub-text-emphasis-position | [ over | under ] && [ right | left ] | No Change |
| -epub-text-emphasis-style | none | [ [ filled | open ] || [ dot | circle | double-circle | triangle | sesame ] ] | <string> | No Change |
| -epub-text-underline-position | auto | [ under || [ left | right ] ] | No Change |
| -epub-text-underline-position | alphabetic | text-underline-position: auto |
Property value syntax defined inComponent value combinators[CSS3 Values and Units].
4.5 Reading System Overrides
EPUB Reading SystemsSHOULD applyAuthor style sheets as written toEPUB Content Documents. If a Reading System allows, usersSHOULD be able to override Author style sheets as desired. EPUB Reading SystemsSHOULD NOT override Author style sheets unless strictly necessary.
If a Reading System has to override an Author style sheet, itSHOULD do so in a way that preserves the Cascade: through a user agent style sheet, thegetOverrideStyle method[DOM2 Style], or[HTML]style attributes.
Developers of Reading Systems are strongly encouraged to publicly document their user agent style sheets and how they interact with Author style sheets.
5. Scripting
5.1 Scripting Contexts
EPUB Content DocumentsMAY contain scripting using the facilities defined for this in the respective underlying specifications ([HTML] and[SVG]). When an EPUB Content Document contains scripting, it is referred to in this specification as aScripted Content Document. This label also applies toXHTML Content Documents when they contain instances of[HTML]forms.
This specification defines two contexts in which scriptsMAY appear:
- spine-level
An instance of the[HTML]script or[SVG]script element included in aTop-level Content Document.
- container-constrained
Either of the following:
In both of the above-defined contexts, whether the JavaScript code is embedded directly in thescript element or referenced via itssrc attribute makes no difference to the executing context.
Which context a script is used in determines the rights and restrictions that a Reading System places on it. Refer toContent Conformance andReading System Conformance for some specific requirements that have to be adhered to (not all Reading Systems will provide the same scripting functionality).
Example
Consider the following example Package Document:
<package …> …<manifest> …<itemid="chap01"href="scripted01.xhtml"media-type="application/xhtml+xml"properties="scripted"/><itemid="inset01"href="scripted02.xhtml"media-type="application/xhtml+xml"properties="scripted"/><itemid="slideshowjs"href="slideshow.js"media-type="text/javascript"/></manifest><spine …><itemrefidref="chap01"/> …</spine> …</package>
and the following filescripted01.xhtml:
<html …><head> …<scripttype="text/javascript"> alert("Reading System name: " + navigator.epubReadingSystem.name);</script></head><body> …<iframesrc="scripted02.xhtml" … /> …</body></html>and the following filescripted02.xhtml:
<html …><head> …<scripttype="text/javascript"href="slideshow.js"></script></head><body> …</body></html>
From these examples, it is true that:
the code in thescript element in thehead inscripted01.xhtml is a spine-level script because the document is referenced from the spine;
the code in thescript element inscripted02.xhtml is a container-constrained script because the HTML file it occurs in is included inscripted01.xhtml via theiframe element.
5.2 Content Conformance
- Container-constrained scripts
A container-constrained scriptMUST NOT contain instructions for modifying the DOM of the parent Content Document or other contents in the EPUB Publication, andMUST NOT contain instructions for manipulating the size of its containing rectangle.
- Spine-level scripts
EPUB Content Documents that includespine-level scriptingMUST utilize theprogressive enhancement technique, which for the purposes of this specification has the following definition: when the document is rendered by a Reading System without scripting support or with scripting support disabled, thetop-level document contentMUST retain its integrity, remaining consumable by the user without any information loss or other significant deterioration.
- Accessibility
EPUB Content Documents thatinclude scriptingSHOULD employ relevant[WAI-ARIA] accessibility techniques to ensure that the content remains consumable by all users.
- Fallbacks
EPUB Content Documents thatinclude scriptingMAY provide fallbacks for such content, either by using intrinsic fallback mechanisms (such as those available for the[HTML]object andcanvas elements) or, when an intrinsic fallback is not applicable, by using amanifest-level[Packages 3.1] fallback.
AuthorsMUST ensure that any output scripts generate meetsCore Media Type requirements[EPUB 3.1].
5.3 Reading System Conformance
A Reading System that supports scriptingMUST meet the following criteria:
ItSHOULD supportcontainer-constrained scripting in reflowable EPUB Content Documents.
ItSHOULD supportspine-level scripting infixed-layout documents.
ItSHOULD support spine-level scripting in reflowable EPUB Content Documents that use the"scrolled-doc" or"scrolled-continuous" presentation modes defined bythe rendition:flow property[Packages 3.1]. Similarly, if it supports spine-level scripting in reflowable EPUB Content Documents, itMUST implement the "scrolled-doc" presentation mode andSHOULD implement the "scrolled-continuous" presentation mode.
ItMAY 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.
ItMAY renderScripted Content Documents as an interactive, scripted user agent according to[HTML].
ItMUST NOT allow a container-constrained script to modify the DOM of the parent Content Document or other contents in the EPUB Publication, andMUST NOT allow it to manipulate the size of its containing rectangle. (Note: Even if a script is not container-constrained, the Reading SystemMAY impose restrictions on modifications (see also thedom-manipulation feature).)
ItMAY place additional limitations on the capabilities provided to scripts during execution (e.g., limiting networking).
ItMUST implement the JavaScriptnavigator extension objectepubReadingSystem defined inAppendix A,JavaScript epubReadingSystem Object. It alsoMUST support thedom-manipulation andlayout-change features defined inFeatures in container-constrained scripting contexts.
A Reading System that does not support scriptingMUST meet the following criteria:
Note
Reading Systems might render Scripted Content Documents in a manner that disables other EPUB capabilities and/or provides a different rendering and user experience (e.g., by disabling pagination).
Authors choosing to restrict the usage of scripting to thecontainer-constrained model will ensure a more consistent user experience between scripted and non-scripted content (e.g., consistent pagination behavior).
Authors are advised to use declarative techniques whenever practical to increase the interoperability, longevity and accessibility of their EPUB Publications, and avoid the inclusion of scripting whenever practical.
5.4 Security Considerations
This section is non-normative.
All EPUBAuthors andEPUB Reading System developers have to 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 need to behave as if a unique domain were allocated to each Content Document, as browser-based security relies heavily on document URLs and domains. Adopting this approach will isolate documents from each other and from other Internet domains, thereby limiting access to external URLs, cookies, DOM storage, etc.
Reading Systems that enable scripting and network access also need to consider including methods to notify the user that network activity is occurring and/or that allow them to disable it.
Note
In practice, Reading Systems might share domains across documents, but they still need to maintain isolation between documents.
If parts of a document are encrypted and parts are not, or if different encryption keys are used for different parts of the document, a unique per-document domain might not provide sufficient protection.
If a Reading System allows persistent data to be stored, that data needs to be treated as sensitive. Scripts might save persistent data through cookies and DOM storage, but Reading Systems might block such attempts. Reading Systems that do allow data to be stored have to 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 also need to provide methods for users to inspect, disable, or 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.
5.5 Event Model Considerations
This section is non-normative.
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 apotentially 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.
Authors need to take into account the wide variety of possible Reading System implementations when adding scripting functionality to their EPUB Publications (e.g., not all devices have physical keyboards, and in many cases a soft keyboard is activated only for text input elements). Consequently, relying on keyboard events alone is not advised; alternative ways to trigger a desired action always need to be provided.
A. Appendix A. JavaScript epubReadingSystem Object
A.1 Interface Definition
This specification extends the[HTML] Navigator object as follows.
[Exposed=(Window)]interfaceEpubReadingSystem { [Unforgeable] readonly attributeDOMStringname; [Unforgeable] readonly attributeDOMStringversion; [Unforgeable]booleanhasFeature(DOMStringfeature,optionalDOMStringversion);};partial interfaceNavigator { [Unforgeable,SameObject] readonly attributeEpubReadingSystemepubReadingSystem;};[WEB IDL] notation.
Note
This specification does not define anepubReadingSystem property extension for theWorkerNavigator object[Web Workers]. Reading Systems therefore do not have to expose theepubReadingSystem object in the scripting context of Workers, and Authors cannot rely on its presence.
A.2 Description
TheepubReadingSystem object provides an interface through which aScripted Content Document can query information about a user'sReading System.
The object exposesproperties of the Reading System (its name and version), and provides thehasFeature method which can be invoked to determine the features it supports.
Example JavaScript function that displays the name of the current Reading System.
alert("ReadingSystemname: " +navigator.epubReadingSystem.name);Reading SystemsMUST expose theepubReadingSystem object on thenavigator object of all loaded Scripted Content Documents, including any nestedcontainer-constrained scripting contexts. Reading SystemsMUST ensure that theepubReadingSystem object is available no later than when theDOMContentLoaded event is triggered[HTML].
Note
Reading systems implementations might create cloned instances of theepubReadingSystem 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.
A.3 Properties
The following propertiesMUST be made available for retrieving information about the Reading System.
| Name | Description |
|---|
| name | Returns aString value representing the name of the Reading System (e.g., "iBooks", "Kindle"). |
| version | Returns aString value representing the version of the Reading System (e.g., "1.0", "2.1.1"). |
A.4 Methods
A.4.1 hasFeature
A.4.1.1 Description
ThehasFeature method returns a boolean value indicating whether any version of the specified feature is supported, orundefined if the specified feature is not recognized.
TheOPTIONALversion 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.
AuthorsSHOULD NOT include theversion parameter when queryingfeatures defined in this specification — these features are considered versionless. If a Reading System supports a feature defined in this specification, itMUST ignore any suppliedversion parameter and return atrue value.
Example JavaScript function that displays whether the current Reading System supports scripted manipulation of the DOM.
var feature ="dom-manipulation";var conformTest = navigator.epubReadingSystem.hasFeature(feature);alert("Feature " + feature +" supported?: " + conformTest);A.4.1.2 Features
The following table lists the set of features that Reading Systems that support theepubReadingSystem objectMUST recognize (i.e., provide a return value for). Support for these features isOPTIONAL.
| Name | Description |
|---|
dom-manipulation | ScriptsMAY make structural changes to the document’s DOM (applies tospine-level scripting only). |
layout-changes | ScriptsMAY modify attributes and CSS styles that affect content layout (applies tospine-level scripting 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 supportsspine-level scripting (e.g., so acontainer-constrained script can determine whether any actions that depend on scripting support in aTop-level Content Document have any chance of success before attempting them). |
Additional featuresMAY 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.
C. Acknowledgements and Contributors
This section is non-normative.
EPUB has been developed by the International Digital Publishing Forum in a cooperative effort, bringing together publishers, vendors, software developers, and experts in the relevant standards.
The EPUB 3.1 specifications were prepared by the International Digital Publishing Forum’s EPUB Maintenance Working Group, operating under a charter approved by the membership in July 2015, under the leadership of:
- Gylling,Markus(International Digital Publishing Forum)Chair (until August 2016)
- Siegman,Tzviya(John Wiley & Sons)Chair
- Conboy,Garth(Google Inc.)Vice-chair; Chair (beginning August 2016)
- Duga,Brady(Google Inc.)Vice-chair
Active members of the working group included:
IDPF Members
- Albert,Paolo(PubCoder)
- Audrain,Luc(Hachette Livre)
- Bailey,Brent(Elsevier)
- Baker,Mike(Houghton Mifflin Harcourt)
- Balakrishnan,Ramu(MPS Limited)
- Belfanti,Paul(Pearson)
- Bell,Graham(EDItEUR)
- Bogan,Robert(Baker & Taylor)
- Bowers,Micah(Bluefire Productions)
- Burrows,Phil(VitalSource/Ingram Content Group)
- Challman,Lauren(Kaplan Publishing)
- Cho,Yong-Sang(KERIS (Korea Education and Research Information Service))
- Cleghorn,Tom(Cambridge University Press)
- Comerford,Rachel(Macmillan)
- Conboy,Garth(Google)
- Corona,Juan(Evident Point)
- Cramer,Dave(Hachette Book Group)
- Creasy,Keith(American Printing House for the Blind, Inc.)
- Davis,Greg(Pearson)
- DeMeglio,Marisa(DAISY Consortium)
- Deltour,Romain(DAISY Consortium)
- Duga,Brady(Google)
- Gardeur,Hadrien(Feedbooks)
- Geffroy,Jean-Marie(Mantano)
- Gusso,Lina(Pearson)
- Gylling,Markus(International Digital Publishing Forum (IDPF))
- Haase,David(Penguin Random House)
- Hanson,Lauren(Kaplan Publishing)
- Harris,Eric(VitalSource/Ingram Content Group)
- Heinser,Bernhard(Access for All)
- Herman,Ivan(W3C)W3C Liaison
- Idan,Ori(Helicon Books)
- Jay,Michael(Educational Systemics)
- Johnson,Rick(VitalSource/Ingram Content Group)
- Jung,Eunmi(KERIS (Korea Education and Research Information Service))
- Kanai,Takeshi(Sony)
- Kasdorf,Bill(Apex CoVantage)
- Keating,Patrick(Bluefire Productions)
- Kennedy,Naomi(Penguin Random House)
- Kerscher,George(DAISY Consortium)
- Khramov,Yuri(Readium)
- Kleinfeld,Sanders(O'Reilly)
- Koike,Toshiaki(Voyager Japan)
- Labordrie,Cyril(EDRLab)
- LaPierre,Charles(Benetech)
- Leo,Arthic(Amnet Systems)
- Levantovsky,Vladimir(Monotype)
- Levenson,Yonah(Pearson)
- Lin,Beatrice(KERIS (Korea Education and Research Information Service))
- Lui,Edwina(Kaplan Publishing)
- McCoy,Bill(IDPF)
- Mietkiewicz,Elie(Gutenberg Technology)
- Mitchell,Chris(Hachette Book Group)
- Moua,Nou(Kaplan Publishing)
- Murata,Makoto(JEPA EPUB Study Group)
- Mussinelli,Christina(Associazione Italiana Editori)
- Owens,Evan(Cenveo Publisher Services)
- Prabhu,John(HOV Services)
- Pritchett,James(Learning Ally)
- Rosenthol,Leonard(Adobe Systems)
- Shyne,Mary(Penguin Random House)
- Siegman,Tzviya(John Wiley & Sons)
- Singh,Avneesh(DAISY Consortium)
- Soiffer,Neil(Design Science)
- Swick,Ralph(W3C)
- Tallent,Joshua(eBookArchitects)
- Thurston,Jonathan(Pearson)
- Webster,Amaya(Benetech)
- Weck,Daniel(DAISY Consortium)
- Wright,Ric(Readium Foundation)
- Andrews,David
- Bonelli,Giuseppe
- Brady,Laura
- Etemad,Elika J.W3C CSS WG Liaison
- Garrish,Matt
- Glazman,Daniel
- Hawkins,Kevin
- Kaplansky,Jean
- Kudou,Tomoyuki
- Leva,Paolo
- Marquès Solé,Daniel
- McGlone,Jonathan
- Morris,Julie
- Munchenburger,Manfred
- Rasmussen,Lloyd
- Reddy,Ramesh
- Rothberg,Madeleine
- Sheehan,John
- White,Jason
For more detailed acknowledgements and information about contributors to each version of EPUB, refer toAcknowledgements and Contributors[EPUB3 Overview].