This specification, EPUB Multiple-Rendition Publications, defines the creation and rendering of EPUB® Publications consisting of more than one rendition.

Introduction

Overview

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:

Taken together, these features enable the creation of advanced multiple-rendition publications that reading systems can adapt to changing user needs.

Background

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).

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.

Terminology

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

It also defines the following terms:

container document

The container.xml file located in the child META-INF directory of the EPUB container root directory [[epub-33]]. Each [=rendition=] in the container is identified by a rootfile element [[epub-33]].

default rendition

The [=rendition=] listed in the first rootfile element in the container.xml file [[epub-33]].

multiple-rendition publication

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.

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

Specifying multiple renditions

Each rendition of an [=EPUB publication=] MUST meet the requirements for EPUB publications [[epub-33]].

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 [=EPUB manifest | manifest=] [[epub-33]]. renditions MAY reference the same publication resources.

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):

/META-INF
/Rendition1
   - rendition1.opf
/Rendition2
   - rendition2.opf
/Shared

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:

/META-INF
/EPUB
   /Rendition1
   /Rendition2
   /Shared
   - rendition1.opf
   - rendition2.opf

Expressing metadata

Rendition metadata

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.

Publication metadata

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 dc:identifier element [[dcterms]] MUST contain the unique identifier [[epub-33]] for the EPUB publication.
  • 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.
  • All other metadata is OPTIONAL.
  • The obsolete OPF2 meta element [[epub-33]] is not allowed.
  • The meta and link elements are defined in the same namespace as the metadata root element: http://www.idpf.org/2013/metadata
  • 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.

The content of this file is also defined informally through an XML schema. See 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).

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.

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.

Resource obfuscation

The resource obfuscation algorithm [[epub-33]] depends on creating an obfuscation key [[epub-33]] from the [=unique identifier=] for the EPUB publication.

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.

Consequently, EPUB creators MUST use the unique identifier of the [=default rendition=] as the obfuscation key for all resources in a [=multiple-rendition publication=].

Similarly, [=reading systems=] MUST use this unique identifier of the default rendition to de-obfuscate all resources in a multiple-rendition publication.

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.

Reserved prefixes [[epub-33]] for metadata attribute expressions are adopted without change.

Rendition selection

Introduction

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.

Content conformance

A container document:

reading system conformance

An EPUB reading system SHOULD determine the rendition to present to a user as defined in .

Rendition selection attributes

The use of the rendition selection attributes in the container.xml file [[epub-33]] is also defined informally through an XML schema. See for further details.

The rendition:media attribute

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).

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.

When specified, the value of this attribute MUST match the global rendition:layout setting [[epub-33]] for the referenced rendition.

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.

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.

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.

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.

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 the default rendition is reached, select that rendition and exit the process.

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.

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.

Rendition mapping

Introduction

The [=rendition mapping document=] identifies related content locations across the [=renditions=] in a [=multiple-rendition publication=], allowing reading systems to switch between renditions while keeping the user's place.

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.

Content conformance

An EPUB publication MAY include a [=rendition mapping document=].

A conformant rendition mapping document:

reading system conformance

Reading systems SHOULD support the use of [=rendition mapping documents=] to switch between content.

A reading system that supports mapping:

EPUB rendition mapping document definition

The content of this file is also defined informally through an XML schema. See for further details.

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 head MAY contain only meta elements. Only the charset attribute or name and content attributes MAY be attached to the meta elements.
  • The head MUST 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.

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 using an Intra-Publication CFI [[epubcfi-11]] as the value of the href attribute or,
    • by having an epub:rendition attribute whose value is the relative path to the Publication Document for the rendition.

Rendition mappings

Each ul element in the [=rendition mapping document=] resource-map nav 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.

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).

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.

Container identification

The location of the [=rendition mapping document=] is identified in the container document using a link element [[epub-33]], where:

  • 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.

Processing model

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:

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.

Schemas

Validation using the schemas in this appendix requires a processor that supports [[relaxng-schema]] and [[xmlschema11-2]].

Metadata.xml Schema

The schema for including metadata in the metadata.xml file, as described in , is available at https://github.com/w3c/epubcheck/blob/main/src/main/resources/com/adobe/epubcheck/schema/30/ocf-metadata-30.rnc.

Container.xml schema

The schema for including rendition selection attributes in the container.xml file, as described in , is available at https://github.com/w3c/epubcheck/blob/main/src/main/resources/com/adobe/epubcheck/schema/30/multiple-renditions/container.rnc.

Mapping document schema

The schema for Mapping Documents, as described in , is available at https://github.com/w3c/epubcheck/blob/main/src/main/resources/com/adobe/epubcheck/schema/30/multiple-renditions/mapping.rnc.

Change log

Note that this change log only identifies substantive changes since EPUB Multiple-Rendition Publications 1.0 — those that affect the conformance of [=EPUB publications=] or are similarly noteworthy.

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