This specification, EPUB Multiple-Rendition Publications, defines the creation and rendering of EPUB®
Publications consisting of more than one rendition.
Status of This Document
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 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.
The
W3C Patent
Policy
does not carry any licensing requirements or commitments on this
document.
The need to include more than one rendition of an EPUB publication has grown as reading systems have evolved and become more sophisticated. While some measure of content adaptation has
always been possible at the style sheet level, it is both limited in what it can accomplish and
limited to content rendering. Existing fallback mechanisms within the package document
similarly only ensure that resources can be rendered.
Adaptation is not just about optimizing styling and positioning content for screen considerations,
such as dimensions and color or reading system orientation, but often involves changing the content
itself. The resources and markup required to render a fixed-layout rendition of an EPUB publication
may overlap with a reflowable version of the same, but the two are never exactly the same.
Adaptation also involves adapting the prose of a work. In an increasingly interconnected world,
including multiple translations of a work rather than bundling them all separately as
single-language EPUB publications is often a necessity. And adaptation is also about the ability to
move from the same spot in one rendition to the equivalent spot in another as changes in the reading
environment occur.
This specification defines how a reading system selects from multiple EPUB creator-provided
renditions of the content to best match the current device characteristics and user preferences
— it does not define methods for modifying content on the fly. As changes occur to device
orientation or the user's preferred reading modality, for example, the reading system will be able
to check for a better rendition and seamlessly present it using the functionality defined
herein.
The specification addresses each of the major requirements in the discovery of, selection of, and
mapping between, multiple renditions of an EPUB publication. In particular:
the establishment of a unique identifier common to all the renditions in the
META-INF/metadata.xml file;
the selection of renditions through a set of attributes that can be attached to
rootfile elements in the container document;
the optional ability to move from a point in one rendition to the same location in another by
means of a mapping document.
Taken together, these features enable the creation of advanced multiple-rendition publications that
reading systems can adapt to changing user needs.
1.2 Background
This section is non-normative.
The notion of including multiple renditions of an EPUB publication has existed for as long as the
EPUB standard, but the specification has never fully addressed what these renditions are for and how
to access them. As a result, the EPUB 3 specification generally equates an EPUB publication with a
single rendering of the content. Moreover, most EPUB creators and reading system developers
equate an EPUB publication with a single package document referenced from the first
rootfile element in the container.xml file [epub-33].
In practice, however, the container.xml file does not restrict EPUB creators to listing
only a single package document. In EPUB 2, for example, EPUB creators could add additional
rootfile elements referencing any other format they desired (e.g., another package
document, a PDF file, or even a Word Document). In EPUB 3, rootfile elements were
restricted to referencing only package documents of the same version of the standard.
This specification moves beyond merely allowing multiple renderings to define a more complete
framework for identifying and selecting from among them. Each package document referenced from a
rootfile element is defined to be one rendition of the EPUB publication, with
the first package document representing the default rendition (i.e., the one that all reading
systems have to process).
Although this model is intended to work as seamlessly as possible with existing the EPUB ecosystem,
the authoring of multiple renditions requires some compromises to maintain compatibility (e.g., some
duplication of metadata will be necessary for reading systems that do not handle multiple
renditions).
1.3 Relationship to EPUB 3
The method defined in this specification for including multiple renditions within an EPUB
container is not required for all EPUB publications. Multiple renditions MAY be included
in a container without adhering to this specification, as the ability to create multiple-rendition
containers pre-dates this specification.
It is strongly RECOMMENDED, however, that all future needs for multiple renditions in a container
follow this specification. Existing implementations that utilize other methods for selecting from
multiple renditions are also encouraged to consider migrating to use this specification to improve
the overall interoperability of multiple-rendition publications.
Some of the rendition selection attributes defined in this
specification share common names with package document elements and properties [epub-33] as they
are designed to reflect that information for selection purposes.
Despite this commonality, this specification does not enforce equivalence between the rendition
selection properties expressed on a rootfile element [epub-33] and the metadata
expressed in the corresponding package document, as direct equivalence is not always possible.
For example, a multilingual EPUB publication will define more than one dc:language element
[epub-33] — one for each language — but for rendition selection only the primary
language is defined. Likewise, the language defined in the package document could include a specific
region code, but for selection purposes the EPUB creator might identify only the language code.
The reason for common metadata in both locations is to simplify the selection process: including
attributes avoids the requirement to parse each referenced package document and allows for
expressions of primacy that are not possible at the package level. It also avoids collisions and
ambiguities between metadata being used for different purposes (selection versus rendering).
The selection properties defined in the container.xml file [epub-33] have no rendering behaviors attached to
them, either. For example, indicating that a rendition is fixed layout in the rendition:layout attribute does not trigger fixed layout rendering
behaviors within the specified rendition.
A reading system renders a rendition according to the metadata expressed in the package document
only.
An EPUB publication that consists of two or more renditions of the content.
rendition
One rendering of the content of an EPUB publication, as expressed by a package document.
rendition mapping document
A specialization of the XHTML content document, containing machine-readable mappings between
equivalent content in different renditions, conforming to the constraints expressed in
rendition mapping.
Note
Only the first instance of a term in a section links to its definition.
1.5 Conformance
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, and SHOULD 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.
The package document for each rendition MUST be listed in the container.xml file
[epub-33], where the first package document listed represents the default rendition.
Each rendition of the EPUB publication SHOULD only list the publication resources necessary for its
rendering in its package document manifest [epub-33]. renditions MAY reference the
same publication resources.
Note
Renditions may not be able to access resources stored in sibling directories on all reading systems
(i.e., some reading systems do not provide access outside the directory a rendition's package
document is stored in).
For example, given the following directory structure (all resources except the package documents
omitted for clarity):
Resources in the "Rendition1" directory may not be able to access resources in either
"Rendition2" or "Shared".
To share resources between renditions, it is recommended that the package documents be located in a
common directory and the resources for each rendition stored in separate subdirectories.
Restructuring the previous example as follows would allow shared access to all resources:
Metadata expressed at the rendition level MAY change from instance to instance. For example,
renditions in different languages will have different primary languages and language-specific
metadata such as titles will be expressed differently. Similarly, bundled fixed-layout and
reflowable renditions will express different rendering metadata.
3.2 Publication metadata
3.2.1 The metadata.xml file
To ensure consistency of metadata at the Publication and rendition levels, this specification
defines the content model of the root metadata element in the metadata.xml file
[epub-33] to be the same as the package document metadata element [epub-33], with the following differences in syntax
and semantics:
A meta element [epub-33] MUST contain the last modified date, expressed using
the dcterms:modified property [dcterms]. The value of the property MUST
conform to the pattern and rules defined in Last modified date [epub-33]. Only
one dcterms:modified property without a refines attribute [epub-33] is allowed.
In order to enable the full expression of metadata in the metadata.xml file,
all attributes allowed on the package element [epub-33] are allowed on the root metadata element.
Note
The content of this file is also defined informally through an XML schema. See A.1 Metadata.xml Schema for further details.
This specification does not define a model for the inheritance of metadata from the Publication
level to the rendition level, as EPUB processing only requires that the default
rendition be recognized by reading systems (i.e., reliance on inheritance could result
in reading systems not locating necessary metadata).
Note
EPUB creators are strongly encouraged to include a complete set of Publication metadata in
the default rendition to ensure cross-compatibility, even when making use of this file.
Titles, languages and other metadata is often not applicable from one rendition to another,
further complicating the sharing of metadata. No assumption can be made that metadata in the
metadata.xml file is applicable to any given rendition, whether the
metadata is expressed in the rendition or not.
Note
As [epub-33] does not define a content model for the metadata.xml file, EPUB
publications that do not conform to this specification can include different metadata. EPUB
publications that are not valid to the content model restrictions in this section are not
valid multiple-rendition publications as defined by this specification, but might still
be valid EPUB 3 publications.
EPUB creators are strongly encouraged to migrate to the content model defined in this
specification, even if not producing multiple-rendition publications, to ensure consistent
processing.
For compatibility reasons, and due to the complexities of being able to share resources
across renditions, this specification does not change this requirement but applies it to all
obfuscated resources in the EPUB container.
Similarly, reading systemsMUST use this unique identifier of the default rendition to
de-obfuscate all resources in a multiple-rendition publication.
3.2.2 Vocabulary association mechanisms
This specification inherits the mechanisms for associating vocabularies defined in Vocabulary Association Mechanisms [epub-33] as
they relate to the package document metadata, with only the following modification: the
prefix attribute MAY be attached only to the root metadata
element.
Although each EPUB publication represents a single work, it is possible to optimize the rendering of
that work in any number of different ways. An issue of a magazine, for example, could include a
fixed layout version (print replica) for rendering on tablet-sized screens with a reflowable version
for smaller cellphone screens where the fixed layout would be scaled to illegibility (or
automatically reflowed in unwanted ways if fixed layouts are not supported).
The EPUB container allows multiple renditions of the content to be included in an EPUB
publication, but does not specify how reading systems are to determine the unique properties of the
renditions listed in the container document, or select between them.
This section redresses this problem by defining both a set of rendition selection attributes that can
be attached to rootfile
elements [epub-33] in the container document and a processing model that allows EPUB
creators to specify which rendition is the best representation depending on various conditions.
Reading systems can then select the appropriate representation from the list of renditions to match
the current configuration and user preferences.
The rendition:media attribute identifies the media features of a reading system the
given rendition is best suitable for rendering on.
Attribute Name
media
Namespace
http://www.idpf.org/2013/rendition
Usage
MAY be specified on container document rootfile elements
[epub-33].
Value
A CSS 3 media query [mediaqueries], where the media type, if specified, MUST only
be the value "all".
As per [mediaqueries], the media query in this attribute MUST evaluate to true in order for the
given rendition to be selected for rendering. Media queries that evaluate to "not all” per 3.1 Error Handling [mediaqueries] SHOULD be
treated as false for the purposes of rendition selection (i.e., the given rendition is not a
valid match).
4.4.2 The rendition:layout attribute
The rendition:layout attribute indicates whether the given rendition is
reflowable or pre-paginated.
Attribute Name
layout
Namespace
http://www.idpf.org/2013/rendition
Usage
MAY be specified on container document rootfile elements
[epub-33].
Value
The value of the attribute MUST be reflowable or
pre-paginated.
If a user layout preference is defined in the reading system, the attribute evaluates to true if
the preference matches the specified value, otherwise it evaluates to false. If no user
preference is defined, the reading system SHOULD ignore the attribute when selecting from the
available renditions.
4.4.3 The rendition:language attribute
The rendition:language attribute indicates that the given rendition is optimized
for the specified language.
Attribute Name
language
Namespace
http://www.idpf.org/2013/rendition
Usage
MAY be specified on container document rootfile elements
[epub-33].
Value
MUST contain a valid language code conforming to [rfc5646].
The rendition:language attribute more precisely identifies the primary language of a
rendition than does the inclusion of dc:language elements in the rendition's
package document, as the presence of dc:language elements only indicates that the
specified languages are prominently used in the prose.
If a user language preference is defined in the reading system, the attribute evaluates to true
if the preference matches the specified value, otherwise it evaluates to false. Several matching
schemes are defined in Section 3 of [rfc4647]. Reading systems can use the most appropriate
matching scheme. If no user preference is defined, the reading system SHOULD ignore the
attribute when selecting from the available renditions.
4.4.4 The rendition:accessMode attribute
The rendition:accessMode attribute identifies the way in which intellectual content
is communicated in a rendition, and is based on the [iso24751-3] "Access Mode"
property.
Attribute Name
accessMode
Namespace
http://www.idpf.org/2013/rendition
Usage
MAY be specified on container document rootfile elements
[epub-33].
Value
MUST be one or more of the values: auditory,
tactile, textual or visual
The rendition:accessMode attribute defines the primary access mode(s) for a given
rendition. For example, although a textual work may include images, audio and video, its primary
means of conveying information is the text. Likewise, a visual work might include alternative
text and/or descriptions, but these adaptations are not listed as a textual mode for the
rendition for the purpose of selection.
The way in which information is encoded also needs to be considered when designating an access
mode. If a work has text components, or is completely textual in nature, but that content is
burned into an image format, the access mode is visual (e.g., character dialogue in a JPEG page
of a comic or a scan of a document).
A rendition MAY include more than one primary access mode. For example, the textual version might
also embed the auditory version using media overlays. In such cases, the attribute should list
each primary access mode that is available.
If a user access mode preference is defined in the reading system, the attribute evaluates to
true if that preference matches any of the access modes defined in it, otherwise it evaluates to
false. If no user preference is defined, the reading system SHOULD ignore the attribute when
selecting from the available renditions.
The rendition:label attribute can be use to inform users
about the nature of the content, particularly where such information is not available, or not
yet standardized, for selection. For example, a tactile rendition could indicate the braille
code and grade in its label, or a textual rendition could be marked as optimized for
text-to-speech rendering, not general use.
4.4.5 The rendition:label attribute
The rendition:label attribute allows each rootfile element [epub-33]
to be annotated with a human-readable name.
Attribute Name
label
Namespace
http://www.idpf.org/2013/rendition
Usage
MAY be specified on container document rootfile elements
[epub-33].
Value
Text.
The rendition:label attribute provides a name for the given rendition (e.g., for
manual rendition selection).
The language of the rendition:label attribute MAY be expressed in an
xml:lang attribute.
The rendition:label attribute is not a selection attribute for the purposes of
evaluating which rendition to render.
4.5 Processing model
This section describes the method by which reading systems locate the optimal rendition to
present to a user.
rendition selection SHOULD occur on initial rendering, and reading systems SHOULD re-evaluate the
selection in response to changes in the user environment (e.g., change in device orientation or
viewport size).
When a change condition is triggered, the reading system SHOULD evaluate the rootfile
elements [epub-33] in the container document as follows, starting with the last
rootfile entry:
If rendition namespaced attributes are set, check each attribute per its definition in 4.4 Rendition selection attributes to determine if the specified conditions are
true:
If all conditions evaluate to true, select the given rendition and exit the selection
process.
If any condition is false, move to the preceding rootfile element and continue the
evaluation process.
If any unrecognized rendition-namespaced attributes are found, they are ignored for the purposes
of evaluating a match.
If no rendition namespaced attributes are found, move to the preceding rootfile element and continue the evaluation process.
If the default rendition is reached, select that rendition and exit the process.
Note
This processing model does not require that the selection process occur on a user's device, or
that all renditions be provided in the container. rendition selection could occur on the server
side of a cloud-based delivery system, for example, and only a single best-match rendition sent
to the device.
Note
Since EPUB 2 reading systems, and EPUB 3 reading systems that do not support multiple-rendition
selection, will render the default rendition, EPUB creators need to consider which rendition
will have the greatest compatibility across reading systems and ensure it is listed first.
A reading system MAY provide the user the option to manually select any of the renditions in the
container. It SHOULD use the rendition:label attribute
attribute value to present the option, when available.
As EPUB did not previously define a rendition selection model, custom selection models might be
encountered in some EPUB publications. When recognized, these selection models SHOULD be utilized.
If both rendition selection attributes conformant to this specification and custom attributes are
defined, the latter SHOULD be ignored.
The rendition mapping document is represented as XHTML, and uses nav elements
with unordered lists to group the mappings. There is no display component to the rendition mapping
document; it is designed to enable automated switching. The lack of a rendering context means that
the XHTML content model for this document is very restrictive, allowing only a single nav
element in the body, to ease both authoring and processing.
To enable the mapping of content locations between renditions, the rendition mapping document's
nav element consists of a series of one or more unordered lists, each of which
represents a common point across all the renditions (e.g., a chapter, a page or a component within a
page). The list items in each unordered list represent the set of equivalent link destinations
across the available renditions for that content (e.g., one link might point to a document
representing one page of a fixed layout rendition, while the equivalent link to a reflowable
rendition might point to the corresponding page break indicator within the XHTML content document
containing the page).
Knowing the position of the user in the current rendition, when a change in context occurs, or is
triggered by the user, the reading system can inspect the sibling list items to determine the EPUB
content document to load that best meets the new conditions.
MUST, when a change in renditions occurs, locate the current position in
the rendition mapping document and load the matching position in the new rendition.
5.4 EPUB rendition mapping document definition
Note
The content of this file is also defined informally through an XML schema. See A.3 Mapping document schema for further details.
5.4.1 XHTML content document: restrictions
The rendition mapping document is a compliant XHTML content document, but with the following
restrictions on the [html] content model:
No attributes are allowed on the html, head, body,
ul and li elements. (The xmlns pseudo-attribute
for namespace declarations is allowed.) The nav element only accepts an
epub:type attribute.
The headMAY contain only meta elements. Only the
charset attribute or name and content attributes MAY be attached to the meta elements.
The headMUST include a meta element whose name
attribute has the value "epub.multiple.renditions.version" and whose
content attribute has the value "1.0". Reading systems MAY
ignore all other meta elements.
The body element MUST include exactly one nav element child whose
epub:type attribute specifies the value "resource-map", and
MAY include one or more optional nav elements. No other [html] content is
allowed as a child of the body.
5.4.2 The nav element: modifications and restrictions
This specification restricts the content model of nav elements and their descendants
in the rendition mapping document as follows:
Each nav element MUST identify its nature in an epub:type
attribute.
The rendition mapping documents uses unordered lists (ul) in place of ordered
lists (ol).
The nav element MAY contain one or more ul element.
Each list item (li) MUST contain exactly one a element (i.e.,
span headings and nested lists are forbidden).
a elements MUST be empty.
The a element MUST specify the rendition it is referring to either:
by having an epub:rendition attribute whose value is the relative path
to the Publication Document for the rendition.
5.4.3 Rendition mappings
Each ul element in the rendition mapping documentresource-mapnav element identifies a content location, listing in its child li
elements where that location is found in each of the available renditions. Consequently, each
ul element MUST contain an li for each rendition.
Note
In order to allow a broad variety of use cases, this specification does not impose any
particular level of mapping granularity. For example, some publications aimed at language
learners may define sentence-level synchronisation points, whereas other types of
publications may only map major sections across renditions.
Each list item in the unordered list MUST identify an EPUB content document, or a fragment
therein, for one of the renditions ‒ defined in a child a element. Each of these
links MUST reference a linear Top-level content
document [epub-33].
Each a element MUST specify which rendition it refers to either 1) by including an
Intra-Publication CFI
[epubcfi-11] in its href attribute, or 2) by providing the relative path to the
package document for the rendition as the value of an epub:rendition attribute.
If the epub:rendition attribute is used to specify the target rendition, any
fragment identifier scheme MAY be used within the URL value of the href attribute
of a elements (e.g., unique identifier, or W3C Media Fragment).
Note
The use of [epubcfi-11] expressions is strongly encouraged over other fragment identifier
schemes (particularly in the context of reflowable XHTML content documents), as they allow
reading systems to ingest rendition mappings without any prior pre-processing. Conversely,
the use of unique identifiers forces reading systems to load the targeted EPUB content
documents and process their DOM in order to sort/compare the link destinations (in relation
to document order). This additional processing has performance implications, and
implementation costs in terms of caching, incremental updating, etc.
the href attribute MUST reference the location of the rendition mapping
document relative to the root of the EPUB container;
the rel attribute MUST specify the value "mapping";
the media-type attribute MUST specify the value
"application/xhtml+xml".
The container document MUST NOT reference more than one mapping document.
5.5 Processing model
This section is non-normative.
This section provides a non-normative model by which the rendition mapping document could be
processed by a reading system. It does not address how or when a reading system should switch
renditions.
The desired outcome of the rendition mapping document's mapping capabilities is to display content in
the new rendition that is equivalent to their location in the current rendition, so that a user
maintains their place during reading. To accomplish this goal, a compliant reading system could
follow these steps to reset the current rendition when a change condition is triggered:
First, it would ascertain the position range in the current rendition:
For a fixed format rendition, this will most likely be the rectangle for the current
viewport.
For a reflowable rendition, this will most likely be the range of text currently shown
on the screen.
Next, it would determine which rendition to navigate to, as defined in 4.5 Processing model.
Finally, the reading system would parse the ul elements to find ones that
contain li elements with child a elements that both specify the
same rendition and intersect the current range:
If there is one and only one such ul element, the reading system would
navigate to the beginning of the range in the new rendition.
If there is more than one such ul element, then the reading system behavior
is undefined. The reading system might prompt the user to select between the new
locations, or might choose between them using its own heuristics.
If no matching ul elements are found, the reading system will have to
determine the location to navigate to in the new rendition as if there was no rendition
mapping document.
Note that what happens during navigation is largely a user experience issue, so a reading system
might choose to consider additional information than above to try to achieve a better outcome.
A. Schemas
This section is non-normative.
Validation using the schemas in this appendix requires a processor that supports [relaxng-schema] and
[xmlschema11-2].
19-Mar-2021: Require the use of the unique identifier in the metadata.xml file for
obfuscating resources and recommend it be the same as the identifier in the default rendition. See
issue 1443.
19-Mar-2021: Added note clarifying that package documents need to be in a common directory to share
resources. See issue 619.
19-Mar-2021: Fixed incorrect reference to link element being a child of the
container element. See issue 584.
24-Dec-2020: The specification no longer makes reference to a release identifier, but the
requirement to include a unique identifier and last modification date in the
metadata.xml file remain for backwards compatibility. See issue 1440.
16-Dec-2020: Terminology and requirements related to renditions of an EPUB publication have been
moved to this specification to simplify readability of both this and the [epub-33] specification.
These changes do not affect the ability to include multiple renditions in an EPUB publication. See
issue 1436.
C. Acknowledgements
This section is non-normative.
The following members of the EPUB 3 Working Group contributed to the development of this specification:
Shadi Abou-Zahra (Amazon)
Will AWAD (Newgen Knowledgeworks)
Noel Ray Barron (Apple Inc.)
Sofia Bautista (Legible Media Inc.)
Leah Brochu (National Network for Equitable Library Service)
Matthew C. Chan (House of Anansi Press)
Yu-Wei Chang (Taiwan Digital Publishing Forum)
Juan Corona (Legible Media Inc.)
Dave Cramer (W3C Invited Expert, chair)
Romain Deltour (DAISY Consortium)
Marisa DeMeglio (DAISY Consortium)
Brady Duga (Google LLC)
Reinaldo Ferraz (NIC.br - Brazilian Network Information Center)
Symon Flaming (Rakuten Group, Inc.)
John Foliot (W3C Invited Expert)
Teenya Franklin (Pearson plc)
Hadrien Gardeur (EDRLab)
Matt Garrish (DAISY Consortium)
Jen Goulden (Crawford Technologies)
David Hall (Apple Inc.)
Ivan Herman (W3C, staff contact)
Tetsu Hoshino (Kodansha, Publishers, Ltd.)
jasen huang (ByteDance)
Norikazu Ishizu (Kadokawa Corporation)
Norihito IYENAGA (Kodansha, Publishers, Ltd.)
Rick Johnson (VitalSource Technologies)
Ken Jones (Circular Software)
Antonio Kamiya (Dentsu Group Inc.)
Deborah Kaplan (W3C Invited Expert)
Bill Kasdorf (Book Industry Study Group)
Hiroshi Kawada (MEDIA DO Co., Ltd.)
George Kerscher (DAISY Consortium)
Kazuhito Kidachi (Mitsue-Links Co., Ltd.)
Masakazu Kitahara (Voyager Japan, Inc.)
Toshiaki Koike (Voyager Japan, Inc.)
Ryo Kuroda (ACCESS CO., LTD.)
Charles LaPierre (Benetech)
Dan Lazin (Google LLC)
Philippe Le Hegaret (W3C)
Laurent Le Meur (EDRLab)
YuYu Lin (Taiwan Digital Publishing Forum)
Farrah Little (National Network for Equitable Library Service)
Victor Lopes (Apple Inc.)
Karan Malhotra (Newgen Knowledgeworks)
Makoto Murata (DAISY Consortium)
Cristina Mussinelli (Fondazione LIA)
Yoichiro Nagao (Kodansha, Publishers, Ltd.)
Theresa O'Connor (Apple Inc.)
Yoshinori Ohmura (SHUEISHA Inc.)
Rachel Osolen (National Network for Equitable Library Service)