Copyright © 1999-2023 International Digital Publishing Forum and World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
EPUB® 3 defines a distribution and interchange format for digital publications and documents. The EPUB format provides a means of representing, packaging, and encoding structured and semantically enhanced web content — including HTML, CSS, SVG, and other resources — for distribution in a single-file container.
This specification defines the authoring requirements for EPUB publications and represents the third major revision of the standard.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the EPUB 3 Working Group as a Proposed Recommendation using the Recommendation track.
Publication as a Proposed Recommendation does not imply endorsement by W3C and its Members.
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. Future updates to this specification may incorporate new features.
The W3C Membership and other interested parties are invited to review the document and send comments through 15 May 2023. Advisory Committee Representatives should consult their WBS questionnaires. Note that substantive technical comments were expected during the Candidate Recommendation review period that ended 21 March 2023.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 2 November 2021 W3C Process Document.
This section is non-normative.
EPUB 3 has been widely adopted as the format for digital books (ebooks), and this revision continues to increase the format's capabilities to better support a wider range of publication requirements, including complex layouts, rich media and interactivity, and global typography features. The expectation is that publishers will utilize the EPUB 3 format for a broad range of content, including books, magazines, and educational, professional, and scientific publications.
This specification represents the core of EPUB 3 and includes the conformance requirements for EPUB publications — the product of the standard. The other specifications that comprise EPUB 3 are as follows:
EPUB 3 Reading Systems [epub-rs-33] — defines the processing requirements for EPUB reading systems — the applications that consume EPUB publications and present their content to users.
EPUB Accessibility [epub-a11y-11] — defines accessibility conformance and discovery requirements for EPUB publications.
These specifications represent the formal list recognized as belonging to EPUB 3 and that contain functionality normatively referenced as part of the standard. The development of extension specifications periodically adds new functionality to EPUB publications. Features and functionality defined outside of core revisions to the standard, while not formally recognized in this specification, are nonetheless available for EPUB creators and reading system developers to use.
The non-normative EPUB 3 Overview [epub-overview-33] provides a general introduction to EPUB 3. A list of technical changes from the previous version is also available in the change log.
This section is non-normative.
This section reviews the organization of this specification through the central product it defines: the EPUB publication.
An EPUB publication is, in its most basic sense, a bundle of resources with instructions on how to render those resources to present the content in a logical order. The types of resources that are allowed in EPUB publication, as well as restrictions on their use, are defined in 3. Publication resources.
A ZIP-based archive with the file extension .epub
bundles the EPUB publication's
resources for distribution. As conformant ZIP archives, EPUB publications can be unzipped by many
software programs, simplifying both their production and consumption.
The container format not only provides a means of determining that the zipped content represents an
EPUB publication (the mimetype
file), but also provides a universally named directory
of non-normative resources (/META-INF
). Key among these resources is the
container.xml
file, which directs reading systems to the available package documents. Refer to 4. Open Container Format (OCF) for more information about the container format.
An EPUB publication is typically represented by a single package document. This document includes metadata used by reading systems to present the content to the user, such as the title and author for display in a bookshelf as well as rendering metadata (e.g., whether the content is reflowable or has a fixed layout). It also provides a manifest of resources and includes a spine that lists the default sequence in which to render documents as a user progresses through the content. Refer to 5. Package document for the requirements for the package document.
The actual content of an EPUB publication — what users are presented with when they begin reading — is built on the Open Web Platform and comes in two flavors: XHTML and SVG. Called EPUB content documents, these documents typically reference many additional resources required for their proper rendering, such as images, audio and video clips, scripts, and style sheets.
Refer to 6. EPUB content documents for detailed information about the rules and requirements to produce EPUB content documents, and [epub-a11y-11] for accessibility requirements.
An EPUB publication also includes another key file called the EPUB navigation document. This document provides critical navigation capabilities, such as the table of contents, that allow users to navigate the content quickly and easily. The navigation document is a specialized type of XHTML content document which also allows EPUB creators to use it in the content (i.e., avoiding one table of contents for machine processing and another for user consumption). Refer to 7. EPUB navigation document for more information about this document.
EPUB publications by default are intended to reflow to fit the available screen space. It is also possible to create publications that have pixel-precise fixed layouts using images and/or CSS positioning. The metadata to control layouts are defined in 8. Layout rendering control.
Media overlay documents complement EPUB content documents. They provide declarative markup for synchronizing the text in EPUB content documents with prerecorded audio. The result is the ability to create a read-aloud experience where reading systems highlight the text as it is narrated. Refer to 9. Media overlays for the definition of media overlay documents.
While conceptually simple, an EPUB publication is more than just a collection of HTML pages and dependent assets in a ZIP package as presented here. Additional information about the primary features and functionality that EPUB publications provide to enhance the reading experience is available from the referenced specifications, and a more general introduction to the features of EPUB 3 is provided in the non-normative [epub-overview-33].
Refer to [epub-rs-33] for the processing requirements for reading systems. Although it is not necessary that EPUB creators read that document to create EPUB publications, an understanding of how reading systems present the content can help craft publications for optimal presentation to users.
This section is non-normative.
The technologies EPUB 3 builds on are constantly evolving. Some, typically referred to as "living" or "evergreen" standards, are subject to change daily and their impact on the validity of EPUB publications is immediate. Others are updated less frequently and the changes may not affect EPUB publications until EPUB 3 undergoes a new revision.
In all cases, it is possible that previously valid features may become obsolete (e.g., due to a lack of support or because of security issues). EPUB creators should therefore be cautious about using any feature without broad support and keep their EPUB conformance checkers up to date.
The [html] standard is continuously evolving — there are no longer versioned releases of it. That standard, in turn, references various technologies that continue to evolve, such as MathML, SVG, CSS, and JavaScript.
The benefit of this approach for EPUB is that EPUB publications always keep pace with changes to the web without the need for new revisions. EPUB creators, however, must keep track of the various changes to HTML and the technologies it references to ensure they keep their processes up to date.
The XHTML profile defined by this specification inherits all definitions of semantics, structure and processing behaviors from HTML unless otherwise specified.
In addition, this specification defines a set of extensions to the [html] document model that EPUB creators may include in XHTML content documents.
This specification does not reference a specific version of [svg], but instead uses an undated reference. Whenever there is any ambiguity in this reference, the latest recommended specification is the authoritative reference.
This approach ensures that EPUB will always keep pace with changes to the SVG standard. EPUB creators, however, must keep track of changes to the SVG standard to ensure they keep their processes up to date.
EPUB 3 supports CSS as defined by the CSS Working Group Snapshot [csssnapshot]. EPUB 3 also maintains some prefixed CSS properties, to ensure consistent support for global languages.
EPUB 3 only supports Presentation Markup [mathml3]. Content Markup is only allowed in structured markup annotations.
This specification relies on a subset of [smil3], from which the media overlays elements and attributes defined in 9.2.2 Media overlay document definition are derived.
This specification refers to the [url] standard for terminology and processing related to URLs expressed in EPUB publications. It is anticipated that new and revised web formats will adopt this standard, but until then this may put this specification in conflict with the internal requirements for some formats (e.g., valid relative paths), specifically with respect to the use of internationalized URLs. If a format does not allow internationalized URLs (i.e., URLs must conform to [rfc3986] or earlier), that requirement takes precedence within those resources.
This specification defines the following terms specific to EPUB 3.
Only the first instance of a term in a section links to its definition.
Codec refers to content that has intrinsic binary format qualities, such as video and audio media types designed for optimum compression or that provide optimized streaming capabilities.
A publication resource that is located within the EPUB container, as opposed to a remote resource which is not.
Refer to 3.6 Resource locations for media type-specific rules for resource locations.
The URL [url] of the root directory representing the OCF abstract container. It is implementation specific, but EPUB creators must assume it has properties defined in 4.2.5 URLs in the OCF abstract container.
The URL of a file or directory in the OCF abstract container, defined in 4.2.5 URLs in the OCF abstract container.
A publication resource that conforms to one of the MIME media types [rfc2046] listed in 3.2 Core media types and, therefore, does not require the provision of a fallback (cf. foreign resource).
The designation "core media type resource" only applies when a resource is used in the rendering of EPUB content documents and foreign content documents. A core media type resource cannot be used in the spine, for example, without a fallback unless it also has the media type of an EPUB content document.
An application that verifies the requirements of this specification against EPUB publications and reports on their conformance.
The ZIP-based packaging and distribution format for EPUB publications defined in 4.3 OCF ZIP container.
EPUB container and OCF ZIP container are synonymous.
A publication resource referenced from the spine or a manifest fallback chain that conforms to either the XHTML or SVG content document definitions.
EPUB content documents contain all or part of the content of an EPUB publication (i.e., the textual, visual and/or audio content).
EPUB creators can include EPUB content documents in the spine without the provision of fallbacks.
An individual, organization, or process that produces an EPUB publication.
The creation of an EPUB publication often involves the work of many individuals, and may be split across multiple organizations (e.g., when a publisher outsources all or part of the work). Depending on the process used to produce an EPUB publication, responsibilities may fall on the organization (e.g., the publisher), the individuals preparing the publication (e.g., technical editors), or automatic procedures (e.g., as part of a publication pipeline). As a result, not every party or process may be responsible for ensuring every requirement is met, but there is always an EPUB creator responsible for the conformance of the final EPUB publication.
Previous versions of this specification referred to the EPUB creator as the
.The section of the package document that lists the publication resources.
Refer to 5.6.1 The manifest
element for more information.
A specialization of the XHTML content document that contains human- and machine-readable global navigation information. The EPUB navigation document conforms to the constraints expressed in 7. EPUB navigation document.
A logical document entity consisting of a set of interrelated resources packaged in an EPUB container.
An EPUB publication typically represents a single intellectual or artistic work, but this specification does not restrict the nature of the content.
A system that processes EPUB publications for presentation to a user in a manner conformant with this specification.
The section of the package document that defines an ordered list of EPUB content documents and foreign content documents. This list represents the default reading order of the EPUB publication.
Refer to 5.7.1 The spine
element for more information.
Exempt resources are a special class of publication resources that reading systems are not required to support the rendering of, but EPUB creators do not have to provide fallbacks for.
Refer to 3.4 Exempt resources for more information.
The name of any type of file within an OCF abstract container, whether a directory or a file within a directory.
The file path of a file or directory is its full path relative to the root directory, as defined by the algorithm specified in 4.2.4 Deriving file paths.
An EPUB content document with fixed dimensions directly referenced from the spine. Fixed-layout documents are designated pre-paginated
in the package document, as defined in 8.2 Fixed layouts.
Any publication resource referenced from a spine
element, or
a manifest fallback chain, that is not an EPUB content document.itemref
When a foreign content document is referenced from a spine itemref
element, it
requires a manifest fallback chain with at least one EPUB content document.
With the exception of XHTML and SVG, all core media type resources are foreign content documents when referenced directly from the spine.
A publication resource with a MIME media type [rfc2046] that does not match any of those listed in 3.2 Core media types. Foreign resources are subject to the fallback requirements defined in 3.3 Foreign resources.
The designation "foreign resource" only applies to resources used in the rendering of EPUB content documents and foreign content documents.
Foreign resource and foreign content document are not interchangeable terms. The types of resources considered foreign when used in the spine is greater than the types of resources considered foreign when used in EPUB content documents.
A resource that is only referenced from a package document
element (i.e., not
also used in the rendering of an EPUB publication.link
Linked resources are not publication resources but may be stored in the EPUB container. They do not require fallbacks.
An XML document that associates the XHTML content document with pre-recorded audio narration to provide a synchronized playback experience, as defined in 9. Media overlays.
Non-codec refers to content types that benefit from compression due to the nature of their internal data structure, such as file formats based on character strings (for example, HTML, CSS, etc.).
The OCF abstract container defines a file system model for the contents of the OCF ZIP container, as defined in 4.2 OCF abstract container.
A publication resource that describes the rendering of an EPUB publication, as defined in 5. Package document. The package document carries meta information about the EPUB publication, provides a manifest of resources, and defines a default reading order.
A resource that contains content or instructions that contribute to the logic and rendering of an EPUB publication. In the absence of this resource, reading systems may not render the EPUB publication as the EPUB creator intends. Examples of publication resources include the package document, EPUB content documents, CSS Style Sheets, audio, video, images, embedded fonts, and scripts.
EPUB creators must list publication resources in the package document manifest and typically bundle them all in the EPUB container (the exception being they may locate resources listed in 3.6 Resource locations outside the EPUB container).
A publication resource that is located outside of the EPUB container, typically, but not necessarily, on the web.
Publication resources within the EPUB container are referred to as container resources.
Refer to 3.6 Resource locations for media type specific rules for resource locations.
The root directory represents the base of the OCF abstract container file system. This directory is virtual in nature.
An EPUB content document that includes scripting or an XHTML content document that
contains [html] form
elements.
Refer to 6.3.2 Scripting for more information.
An EPUB content document that conforms to the constraints expressed in 6.2 SVG content documents.
The rendering of two adjacent pages simultaneously on a device screen.
An EPUB content document or foreign content document referenced from the spine, whether directly or via a fallback chain.
The primary identifier for an EPUB publication. The unique identifier is the value of
the
element specified by the dc:identifier
unique-identifier
attribute in the package document.
Significant revision, abridgement, etc. of the content requires a new unique identifier.
The region of an EPUB reading system in which an EPUB publication is rendered visually to a user.
An EPUB content document that conforms to the profile of [html] defined in 6.1 XHTML content documents.
XHTML content documents use the XML syntax defined in [html].
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, REQUIRED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
All algorithm explanations are non-normative.
This section is non-normative.
In package document metadata examples, reserved prefixes are used without declaration.
References to Dublin Core elements [dcterms] use the dc:
prefix. This prefix must be
declared in the package document for their use to be valid
(xmlns:dc="http://purl.org/dc/elements/1.1/"
)
The epub
namespace prefix [xml-names] is also used on elements and attributes without
always having an explicit declaration (xmlns:epub="http://www.idpf.org/2007/ops"
).
An EPUB publication:
MUST define at least one rendering of its content as follows:
MUST contain a package document that conforms to 5. Package document and meet all publication resource requirements for the package document.
SHOULD conform to the accessibility requirements defined in [epub-a11y-11].
MUST be packaged in an EPUB container as defined in 4. Open Container Format (OCF).
In addition, all publication resources MUST adhere to the requirements in 3. Publication resources.
The rest of this specification covers specific conformance details.
This section is non-normative.
Due to the complexity of this specification and number of technologies used in EPUB publications, EPUB creators are advised to use an EPUB conformance checker to verify the conformance of their content.
EPUBCheck is the de facto EPUB conformance checker used by the publishing industry and has been updated with each new version of EPUB. It is integrated into a number of authoring tools and also available in alternative interfaces and other languages (for more information, refer to its Apps and Tools page).
When verifying their EPUB publications, EPUB creators should ensure they do not violate the requirements of this specification (practices identified by the keywords "MUST", "MUST NOT", and "REQUIRED"). These types of issues will often result in EPUB publications not rendering or rendering in inconsistent ways. These issues are typically reported as errors or critical errors.
EPUB creators should also ensure that their EPUB publications do not violate the recommendations of this specification (practices identified by the keywords "SHOULD", "SHOULD NOT", and "RECOMMENDED"). Failure to follow these practices does not result in an invalid EPUB publication but may lead to interoperability problems and other issues that impact the user reading experience. These issues are typically reported as warnings.
Vendors, distributors, and other retailers of EPUB publications should consider the importance of recommended practices before basing their acceptance or rejection on a zero-issue outcome from an EPUB conformance checker. There will be legitimate reasons why EPUB creators cannot follow recommended practices in all cases.
This section is non-normative.
An EPUB publication is made up of many different categories of resources, not all of which are mutually exclusive. Some resources are publication resources, some are not. Some publication resources are allowed in the spine by default, while all others require fallbacks. Some resources can be used in rendering EPUB content documents, while others can only be used with fallbacks.
Trying to understand these differences by reading the technical definitions of each category of resource can be complex. To make the categorizations easier to understand, this introduction uses the concept of different planes to explain how resources are grouped and referred to.
The three planes are:
The same resource may exist on more than one plane and will be referred to differently in this specification depending on which plane is being discussed. For example, a core media type resource used in the rendering of an EPUB content document (on the content plane) may also be a foreign content document if it is also listed in the spine (the spine plane).
The following sections describe these planes in more detail.
Refer to H.1 Resources for a detailed example showing how resources fit into the different planes.
To manifest plane defines all the resources of an EPUB publication. It is analogous to the package document manifest, but includes resources not present in that list.
The primary resources in this group are designated publication resources, which are all the
resources used in rendering an EPUB publication to the user. EPUB creators always have to
list these resources in the
element.manifest
Publication resources are further classified by their use(s) in the spine plane and content plane.
The manifest plane also contains a set of linked resources. These resources are tangential to the direct rendering. They include, for example, metadata records and links to external content (e.g., where to purchase an EPUB publication).
Unlike publication resources, they are not listed in the package document manifest (i.e., because
they are not essential to rendering the EPUB publication). They are instead defined in
elements in the package document metadata. These elements define their nature and purpose
similar to how manifest link
elements define publication resource. (In this way, they are
like an extension of the manifest.)item
Refer to 5.5.7 The link
element for more information about linked resources.
Resources in the manifest plane are also sometimes broken down by where they are located. Although most publication resources have to be located in the EPUB container (called container resources), EPUB 3 allows audio, video, font and script data resources to be hosted outside the container. These exceptions were made to speed up the download and loading of EPUB publications, as these resources are typically quite large, and, in the case of fonts, not essential to the presentation. When remotely hosted, these publication resources are referred to as remote resources.
Since linked resources are not essential to the rendering of an EPUB publication, there are no requirements on where they are located and consequently no special naming of them based on their location. They may be located within the EPUB container or outside it.
Hyperlinked content outside the EPUB container (e.g., web pages) are not publication resources, and consequently are not listed in the manifest. Reading systems will normally open these links in a separate browser instance, not as part of the EPUB publication.
The spine plane defines resources used in the default reading order established by the spine, which includes both linear and non-linear content. The spine instructs reading systems on how to load these resources as the user progresses through the EPUB publication. Although many resources may be bundled in an EPUB container, they are not all allowed by default in the spine.
EPUB 3 defines a special class of resources called EPUB content documents that EPUB creators can use in the spine without any restrictions. EPUB content documents encompass both XHTML content documents and SVG content documents.
To use any other type of resource in the spine, called a foreign content document, requires including a fallback to an EPUB content document. This extensibility model allows EPUB creators to experiment with formats while ensuring that reading systems are always able to render something for the user to read, as there is no guarantee of support for foreign content documents.
A mechanism called manifest fallbacks allows EPUB creators
to provide fallbacks for foreign content documents. In this model, the manifest entry for the foreign content document must include a fallback
attribute that points to the next
possible resource for reading systems to try when they do not support its format. Although not
common, a fallback resource can specify another fallback, thereby making chains many resources
deep. The one requirement is that there must be at least one EPUB content document in a
manifest fallback chain.
Although they are not directly listed in the spine, all of the resources in the fallback chain are considered part of the spine, and by extension part of the spine plane, since any may be used by a reading system.
Refer to 3.5.1 Manifest fallbacks for more information.
Although manifest fallbacks fulfill the technical requirements of EPUB, there is little practical support for them in reading systems. Their use is strongly discouraged as it can lead to unreadable publications.
It is possible to provide manifest fallbacks for EPUB content documents, but this is not required or common. For example, a scripted content document could have a fallback to an unscripted alternative for reading systems that do not support scripting.
The content plane classifies resources that are used when rendering EPUB content documents and foreign content documents. These types of resources include embedded media, CSS style sheets, scripts, and fonts. These resources fall into three categories based on their reading system support: core media type resources, foreign resources, and exempt resources.
A core media type resource is one that reading systems have to support, so it can be used without restriction in EPUB or foreign content documents. For more information about core media type resources, refer to 3.2 Core media types.
Being a core media type resource does not mean that reading systems will always render the resource, as not all reading systems support all features of EPUB 3. A reading system without a viewport, for example, will not render visual content such as images.
The opposite of core media type resources are foreign resources. These are resources that reading systems are not guaranteed to support the rendering of. As a result, similar to how using foreign content documents in the spine requires fallbacks to ensure their rendering, using foreign resources in content documents also requires fallbacks. These fallbacks are provided in one of two ways: using the capabilities of the host format or via manifest fallbacks.
The preferred method is to use the fallback capabilities of the host format. Many HTML elements,
for example, have intrinsic fallback capabilities. One example is the picture
element [html], which allows EPUB creators to specify multiple alternative image
formats.
If an intrinsic fallback method is not available, it is also possible to use manifest fallbacks, but this method, as cautioned against in the previous section, is discouraged. For more information about foreign resources, refer to 3.3 Foreign resources.
Falling between core media type resources and foreign resources are exempt resources. These are most closely associated with foreign resources, as there is no guarantee that reading systems will render them. But like core media types, they do not require fallbacks.
Exempt resources tend to address specific cases for which there are no core media types defined,
but for which providing a fallback would prove cumbersome or unnecessary. These include
embedding video, adding accessibility tracks, and linking to resources from the [html] link
element.
Refer to 3.4 Exempt resources for more information about these exceptions.
A common point of confusion arising from core media type resources is the listing of XHTML and SVG as core media type resources with the requirement the markup conform to their respective EPUB content document definitions. This allows EPUB creators to embed both XHTML and SVG documents in EPUB content documents while keeping consistent requirements for authoring and reading system support.
In practice, it means that EPUB creators can put XHTML and SVG core media type resources in the spine without any modification or fallback (they are also conforming XHTML and SVG content documents), but this is a unique case. All other core media type resources become foreign content documents when used in the spine (i.e., foreign content documents include all foreign resources and all core media type resources except for XHTML and SVG).
EPUB creators MAY include publication resources that conform to the MIME media type [rfc2046] specifications defined in the following table without fallbacks when they are used in EPUB content documents and foreign content documents. These resources are classified as core media type resources.
With the exception of XHTML content documents and SVG content documents, EPUB creators MUST provide manifest fallbacks for core media type resources referenced directly from the spine. In this case, they are foreign content documents.
The columns in the table represent the following information:
Media Type—The MIME media type [rfc2046] used to represent the given publication resource in the manifest.
If the table lists more than one media type, the first one is the preferred media type. EPUB creators should use the preferred media type for all new EPUB publications.
Media Type | Content Type Definition | Applies to |
---|---|---|
Images | ||
image/gif
|
[gif] | GIF Images |
image/jpeg
|
[jpeg] | JPEG Images |
image/png
|
[png] | PNG Images |
image/svg+xml
|
SVG content documents | SVG documents |
image/webp
|
[webp-container], [webp-lb] | WebP Images |
Audio | ||
audio/mpeg
|
[mp3] | MP3 audio |
audio/mp4
|
[mpeg4-audio], [mp4] | AAC LC audio using MP4 container |
audio/ogg; codecs=opus
|
[rfc7845] | OPUS audio using OGG container |
Style | ||
text/css
|
CSS Style Sheets | CSS Style Sheets. |
Fonts | ||
|
[truetype] | TrueType fonts |
|
[opentype] | OpenType fonts |
|
[woff] | WOFF fonts |
font/woff2
|
[woff2] | WOFF2 fonts |
Other | ||
application/xhtml+xml
|
XHTML content documents | HTML documents that use the XML syntax [html]. |
|
[rfc4329] | Scripts. |
application/x-dtbncx+xml
|
[opf-201] | The legacy NCX. |
application/smil+xml
|
Media overlays | EPUB media overlay documents |
Inclusion as a core media type resource does not mean that all reading systems will support the rendering of a resource. Reading system support also depends on the capabilities of the application (e.g., a reading system with a viewport must support image core media type resources, but a reading system without a viewport does not). Refer to Core media types [epub-rs-33] for more information about which reading systems rendering capabilities require support for which core media type resources.
The Working Group typically only includes formats as core media type resources when they have broad support in web browser cores — the rendering engines that EPUB 3 reading systems build upon. They are an agreement between reading system developers and EPUB creators to ensure the predictability of rendering of EPUB publications.
A foreign resource, unlike a core media type resource is one which is not guaranteed reading system support when used in an EPUB content document or foreign content document.
EPUB creators MUST provide fallbacks for foreign resources, where fallbacks take one of the following forms:
intrinsic fallback mechanisms provided by the host format (e.g., [html] elements often provide the ability to reference more than one media type or to display an alternate embedded message when a media type cannot be rendered); or
manifest fallback chains defined on
elements
in the package document.item
Refer to the [html] and [svg] specifications for the intrinsic fallback capabilities their elements provide.
3.5.2 Intrinsic fallbacks also provides additional information about how fallbacks are interpreted for specific elements.
An exempt resource shares properties with both foreign resources and core media type resources. It is most similar to a foreign resource in that it is not guaranteed reading system support, but, like a core media type resource, does not require a fallback.
There are only a small set of special cases for exempt resources. Video, for example, are exempt from fallbacks because there is no consensus on a core media type video format at this time (i.e., there is no format to fallback to). Similarly, audio and video tracks are exempt to allow EPUB creators to meet accessibility requirements using whatever format reading systems support best.
The following list details cases of content-specific exempt resources, including any restrictions on where EPUB creators can use them.
All font resources not already covered as font core media types are exempt resources.
This exemption allows EPUB creators to use any font format without a fallback, regardless of reading system support expectations, as CSS rules will ensure a fallback font in case of no support.
Refer to the reading system support requirements for fonts [epub-rs-33] for more information.
Any resource referenced from the [html] link
element that is not already a core media type resource (e.g.,
CSS style sheets) is an exempt resource.
All audio and video tracks (e.g., [webvtt] captions, subtitles and descriptions)
referenced from the [html] track
element are exempt resources.
All video codecs referenced from the [html] video
— including any child source
elements — are exempt resources.
Although reading systems are encouraged to support at least one of the H.264 [h264] and VP8 [rfc6386] video codecs, support for video codecs is not a conformance requirement. EPUB creators must consider factors such as breadth of adoption, playback quality, and technology royalties when deciding which video formats to include.
The exemptions made above do not apply to the spine. If an exempt resource is used in the spine, and it is not also an EPUB content document, it will require a fallback in that context.
In addition to the content-specific exemptions, a resource is classified as an exempt resource if:
it is not referenced from a spine
element (i.e., used as a foreign content document); anditemref
it is not embedded directly in EPUB content documents (e.g., via [html] embedded content and [svg] image
and foreignObject
elements).
This exemption allows EPUB creators to include resources in the EPUB container that are not for use by EPUB reading systems. The primary case for this exemption is to allow data files to travel with an EPUB publication, whether for scripts to use in their constituent EPUB content documents or for external applications to use (e.g., a scientific journal might include a data set with instructions on how to extract it from the EPUB container).
It also allows EPUB creators to use foreign resources in foreign content documents without reading systems or EPUB conformance checkers having to understand the fallback capabilities of those resources (i.e., the requirement for a fallback for the foreign content document covers any rendering issues within it). As the resource is not referenced from an EPUB content document, it automatically becomes exempt from fallbacks.
Manifest fallbacks are a feature of the package document that create a manifest fallback chain for a publication resource, allowing reading systems to select an alternative format they can render.
Fallback chains are created using the fallback
attribute on manifest
elements. This attribute references
the ID [xml] of another manifest item
item
that is a
fallback for the current item
. The ordered list of all the references that a
reading system can reach, starting from a given item
's fallback
attribute, represents the full fallback chain for that item
. This chain also
represents the EPUB creator's preferred fallback order.
There are two cases for manifest fallbacks:
EPUB creators MUST specify a fallback chain for a foreign content document to ensure that reading systems can always render the spine item. In this case, the chain MUST contain at least one EPUB content document.
EPUB creators MAY provide fallbacks for EPUB content documents (e.g., to provide a fallback for scripted content).
When a fallback chain includes more than one EPUB content document, EPUB creators can use
the properties
attribute to differentiate
the purpose of each.
The original purpose for content fallbacks was to specify fallback images for the
[html] img
element. As HTML now has intrinsic fallback mechanism for images,
the use of content fallbacks is strongly discouraged. EPUB creators should always
use the intrinsic fallback capabilities of [html] and [svg] to provide fallback
content.
EPUB creators MUST provide a content fallback for foreign resources when the elements that reference them do not have intrinsic fallback capabilities. In this case, the fallback chain MUST contain at least one core media type resource.
EPUB creators MAY also provide manifest fallbacks for core media type resources (e.g., to allow reading systems to select from more than one image format).
Regardless of the type of manifest fallback specified, fallback chains MUST NOT contain
self-references or circular references to item
elements in the chain.
As it is not possible to use manifest fallbacks for resources represented in data URLs, EPUB creators can only represent foreign resources as data URLs where an intrinsic fallback mechanism is available.
The following sections provide additional clarifications about the intrinsic fallback requirements of specific elements.
EPUB creators MUST NOT use embedded
[html] flow content within a media
element (i.e, audio
or video
) as an intrinsic fallback for
audio foreign resources. Only child source
elements [html] provide intrinsic
fallback capabilities.
Only older reading systems that do not recognize the audio
or the
video
elements (e.g., EPUB 2 reading systems) will render the embedded
content. When reading systems support these elements but not the available media formats,
they do not render the embedded content for the user.
The requirement for fallbacks only applies to audio foreign resources referenced from
audio
and video
elements. Fallbacks are not required for
video resources; they are exempt resources.
Due to the variety of sources that EPUB creators
can specify in the [html] img
element, the following fallback conditions apply to its
use:
If it is the child of a picture
element:
src
and
srcset
attributes, when EPUB creators specify those attributes;
andsource
element MUST reference a core media type resource
from its src
and srcset
attributes unless it specifies the MIME media type [rfc2046] of a foreign resource in its type
attribute.src
and
srcset
attributes provided EPUB creators define a manifest fallback.Although data blocks have a separate MIME media type [rfc2046] from their containing
XHTML content document, it is not possible to provide intrinsic fallbacks as no such
mechanisms are specified for the [html] script
element. It is also not possible to
provide manifest fallbacks because data blocks cannot be defined as standalone files in the
EPUB container but are always embedded as inline script
elements.
But, as the script
element does not represent user content — data blocks are not rendered unless manipulated by
script, and content rendered by scripts already has core
media type requirements — requiring fallbacks for the raw data does not serve a
useful purpose.
Consequently, to ensure that EPUB creators can include data blocks for scripting purposes, they are exempt from fallback requirements.
This exemption aligns data blocks with the exemption for data files.
[svg] does not define data blocks as of publication, but the same exclusion would apply if a future update adds the concept.
EPUB creators MAY host the following types of publication resources outside the EPUB container:
EPUB creators MUST store all other resources within the EPUB container.
Storing all resources inside the EPUB container is strongly encouraged whenever possible as it allows users access to the entire presentation regardless of connectivity status.
When resources have to be located outside the EPUB container, EPUB creators are RECOMMENDED to
reference them via the secure https
URI scheme [rfc7230] to limit the threat of
exposing their publications, and users, to network attacks. Reading systems might not load
remote resources referenced using insecure schemes such as http
.
These rules for locating publication resource apply regardless of whether the given resource is a core media type resource or a foreign resource.
Refer to the remote-resources
property for more
information on how to indicate that a manifest
references a
remote resource.item
The data:
URL scheme [rfc2397] is used to encode resources
directly into a URL string. The advantage of this scheme is that it allows EPUB creators to
embed a resource within another, avoiding the need for an external file.
EPUB creators MUST NOT use data URLs in the following scenarios where they can result in a top-level content document or top-level browsing context [html]:
in href
attributes in the package document — this applies both to manifest
elements and metadata item
elements;link
in the href
attribute on [html] or [svg] a
elements, except
when inside an iframe
element [html];
in the href
attribute on [html] area
elements, except when inside
an iframe
element;
in calls to [ecmascript] window.open
or document.open
.
These restrictions on the use of data URLs are to prevent security issues and also to ensure that reading systems can determine where to take a user next (i.e., because data URLs cannot be referenced from the spine).
The list of prohibited uses for data URLs is subject to change as the respective standards that allow their use evolve.
A consequence of embedding is that the data in a data URL is not considered its own unique publication resource for manifest reporting purposes (i.e., only its containing publication resource gets listed). As this data has its own media type, however, it is still subject to foreign resource restrictions. EPUB creators MUST therefore encode data URLs as core media type resources or provide a fallback using the intrinsic fallback mechanisms of the host format.
The file:
URL scheme is defined in [rfc8089] as
"identifying an object (a 'file') stored in a structured object naming and accessing environment on
a host (a 'file system')." It is typically used to retrieve files from the local operating
system.
Using a file URL in an EPUB publication, which can be transferred among different hosts, represents a security risk and is also non-interoperable. As a consequence, EPUB creators MUST NOT use file URLs in EPUB publications.
Any publication resource that is an XML-based media type [rfc2046]:
MUST be a conformant XML 1.0 Document as defined in Conformance of Documents [xml-names].
MAY only specify a document type declaration that references an external identifier appropriate for its media type — as defined in B. Allowed external identifiers — or that omits external identifiers [xml].
MUST NOT contain external entity declarations in the internal DTD subset [xml].
MUST NOT make use of XInclude [xinclude].
MUST be encoded in UTF-8 or UTF-16 [unicode], with UTF-8 as the RECOMMENDED encoding.
The above constraints apply regardless of whether the given publication resource is a core media type resource or a foreign resource.
This section is non-normative.
OCF is the required container technology for EPUB publications. OCF may play a role in the following workflows:
This section defines the rules for structuring the file collection in the abstract: the "abstract container". It also defines the rules for the representation of this abstract container within a ZIP archive: the "physical container". The rules for ZIP physical containers build upon the ZIP technologies used by [odf].
OCF also defines a standard method for obfuscating embedded fonts for those EPUB publications that require this functionality.
This section is non-normative.
The OCF abstract container file system model uses a single common root directory. All container resources are located within the directory tree headed by the root directory, but no specific file system structure for them is mandated by this specification.
The file system model also includes a mandatory directory named META-INF
that is a
direct child of the root directory and stores the following special files:
container.xml
[required]
Identifies one or more package documents that define the EPUB publication.
signatures.xml
[optional]
Contains digital signatures for various assets.
encryption.xml
[optional]
Contains information about the encryption of publication resources. This file is mandatory when EPUB creators use font obfuscation.
metadata.xml
[optional]
Used to store metadata about the OCF ZIP container.
rights.xml
[optional]
Used to store information about digital rights.
manifest.xml
[optional]
A manifest of container contents as allowed by Open Document Format [odf].
Refer to 4.2.6 META-INF
directory for conformance requirements for the various files
in the META-INF
directory.
The virtual file system for the OCF abstract container MUST have a single common root directory for all the contents of the container.
The OCF abstract container MUST include a directory for configuration files named
META-INF
that is a direct child of the container's root directory. Refer to 4.2.6 META-INF
directory for the requirements for the contents of this
directory.
The file name mimetype
in the root directory is reserved for use by OCF ZIP containers, as explained in 4.3 OCF ZIP container.
Files in the META-INF
directory and the mimetype
file are not
publication resources so MUST NOT be listed in the manifest.
EPUB creators MAY locate all other files within the OCF abstract container in any location
descendant from the root directory, provided they are not within the META-INF
directory. EPUB creators MUST NOT reference files in the META-INF
directory from an
EPUB publication.
Some reading systems do not provide access to resources outside the directory where the package document is stored. EPUB creators should therefore place all resources at or below the directory containing the package document to avoid interoperability issues.
This problem is more commonly encountered when creating multiple renditions [epub-multi-rend-11] of the publication.
In the context of the OCF abstract container, file paths and file names are scalar value strings [infra] (i.e., their values are case sensitive).
In addition, the following restrictions are designed to allow file paths and file names to be used without modification on most operating systems:
File names MUST NOT exceed 255 bytes.
The file paths for any directory or file within the OCF abstract container MUST NOT exceed 65535 bytes.
File names MUST NOT use the following [unicode] characters, as commonly used operating systems may not support these characters consistently:
SOLIDUS: /
(U+002F
)
QUOTATION MARK: "
(U+0022
)
ASTERISK: *
(U+002A
)
FULL STOP as the last character: .
(U+002E
)
COLON: :
(U+003A
)
LESS-THAN SIGN: <
(U+003C
)
GREATER-THAN SIGN: >
(U+003E
)
QUESTION MARK: ?
(U+003F
)
REVERSE SOLIDUS: \
(U+005C
)
VERTICAL LINE: |
(U+007C
)
DEL (U+007F
)
C0 range (U+0000 … U+001F
)
C1 range (U+0080 … U+009F
)
Private Use Area (U+E000 … U+F8FF
)
All Unicode Non Characters, specifically:
The 32 contiguous characters in the Basic Multilingual Plane
(U+FDD0 … U+FDEF
)
The last two code points of the Basic Multilingual Plane
(U+FFFE
and U+FFFF
)
The last two code points at the end of the Supplementary Planes
(U+1FFFE, U+1FFFF … U+EFFFE, U+EFFFF
)
Specials (U+FFF0 … U+FFFF
)
Supplementary Private Use Area-A (U+F0000 … U+FFFFF
)
Supplementary Private Use Area-B (U+100000 … U+10FFFF
)
The Unicode Character Database [uax44] also includes a list of deprecated characters. EPUB creators are advised to avoid these characters, as well, as it is expected that EPUB conformance checkers will flag their use.
For compatibility with older reading systems, file names SHOULD NOT contain SPACE (U+0020) characters.
All file names within the same directory MUST be unique following Unicode canonical normalization [uax15] and then full case folding [unicode]. (Refer to Unicode Canonical Case Fold Normalization Step [charmod-norm] for more information.)
If EPUB creators dynamically integrate resources (i.e., where the naming is beyond their control), they should be aware that automatic truncation of file names to keep them within the 255 bytes limit can lead to corruption. This is due to the difference between bytes and characters in multibyte encodings such as UTF-8; it is, therefore, important to avoid mid-character truncation. See the section on "Truncating or limiting the length of strings" in [international-specs] for more information.
EPUB creators should use an abundance of caution in their file naming when interoperability of content is key. The list of restricted characters is intended to help avoid some known problem areas, but it does not ensure that all other Unicode characters are supported. Although Unicode support is much better now than in earlier iterations of EPUB, older tools and toolchains may still be encountered (e.g., ZIP tools that only support [us-ascii]).
To derive the file path, given a file or directory file in the OCF abstract container, apply the following steps (expressed using the terminology of [infra]):
U+002F (/)
character.The container root URL is the URL [url] of the root directory. It is implementation-specific, but EPUB creators MUST assume it has the following properties:
/
" with the container root URL as base is the container root URL...
" with the container root URL as base is the container root URL.The content URL of a file or directory in the OCF abstract container is the result of parsing the file's file path with the container root URL as base.
The container root URL is the URL assigned by the reading system to the root of the EPUB container. It typically depends on how the reading system internally implements the container file system.
However, a reading system cannot arbitrarily use any URL, but one that honors the constraints defined above. These constraints ensure that any relative URL string found in the EPUB will always be parsed to a URL of a resource within the container (which may or may not exist). The primary reason for these constraints is to avoid potential run-time security issues that would be caused by parsed URLs "leaking" outside the container files.
For example, URLs like https://localhost:12345/
or
https://www.example.org:12345/
honor these properties. But URLs like
https://localhost:12345/path/to.epub/
,
file:///path/to.epub#path=/
, or jar:file:/path/to.epub!/EPUB/
do not (parsing the URL string "..
" with these three examples as base would
return https://localhost:12345/path/
, file:///path/
, and a parsing
error, respectively). It is the responsibility of the reading system to assign a URL to the
root directory that complies with the properties defined above.
Parsing may replace some characters in the file path by their percent encoded alternative. For example,
A/B/C/file name.xhtml
becomes A/B/C/file%20name.xhtml
.
A string url is a valid-relative-ocf-URL-with-fragment string if it is a
path-relative-scheme-less-url string, optionally followed by U+0023 (#)
and a url-fragment string, and if the following steps return true:
Set the container root URL to https://a.example.org/A/
.
The goal of the algorithm is to detect whether url could be seen as
"leaking" outside the container. To do that, the standard URL parsing algorithm is used with an artificial root URL; the detection of the "leak" is done
by comparing the result of the parsing with the presence of the first test path
segment (A
). (Note that the artificial container root URL wilfully
violates, for the purpose of this algorithm, the required properties by using that first test path segment.)
Let base be the base URL that must be used to parse url as defined by the context (document or environment) where url is used, and according to the content URL of the package document (see 5.2 Parsing URLs in the package document).
In the case of a URL in the package document the base variable is set to
the content URL of the package document. In the case of a document within the
META-INF
directory, the base variable is set to the
container root URL (see 4.2.6.2 Parsing URLs in the META-INF
directory). In the case of a
URL in an XHTML content document, the base URL used for parsing is defined by
the HTML standard. Typically, it will be the
content URL of the content document (unless the discouraged
base
element is used).
Set the container root URL to https://b.example.org/B/
.
The reasons to repeat the same steps twice with different, and artificial, settings
of the container root URL is to avoid collision which may occur if the
url string also includes /A/
. Consider, for example, the
case where url is ../../A/doc.xhtml
.
If testURLStringA does not start with https://a.example.org/
or
testURLStringB does not start with https://b.example.org/
,
return true.
If any of the result does not share the test URL host, it means that url,
or its base URL (for example, in HTML, if it is explicitly set with the
base
element), was absolute and points outside the
container. This is acceptable.
If testURLStringA starts with https://a.example.org/A/
and
testURLStringB starts with https://b.example.org/B/
, return
true.
The presence of the first test path segments (A
, respectively
B
) indicate that the URL doesn't leak outside the container.
In the OCF abstract container, any URL string MUST be an absolute-url-with-fragment string or a valid-relative-ocf-URL-with-fragment string.
In addition, all relative-URL-with-fragment strings [url] MUST, after parsing, be equal to the content URL of an existing file in the OCF abstract container.
These constraints on URL strings mean that:
/
(U+002F
) (for example,
/EPUB/content.xhtml
) are disallowed; EPUB/../../../../config.xml
) are
disallowed; Note that in any case, even the disallowed URL strings described above will not "leak" outside the container after parsing (as explained in the first note of this section). They are nevertheless disallowed for better interoperability with non-conforming or legacy reading systems and toolchains.
All OCF abstract containers MUST include a directory called META-INF
in
their root directory.
This directory is reserved for configuration files, specifically those defined in 4.2.6.3 Reserved files.
To parse a URL string
url used in files located in the META-INF
directory the URL parser MUST be applied to url, with the
container root URL as base.
The REQUIRED container.xml
file in the META-INF
directory
identifies the package documents available in the OCF abstract container.
All [xml] elements defined in this section are in the
urn:oasis:names:tc:opendocument:xmlns:container
namespace [xml-names]
unless specified otherwise.
The contents of this file MUST be valid to the definition in this section after removing all elements and attributes from other namespaces (including all attributes and contents of such elements).
An XML Schema also informally defines the content of this file.
The container
element encapsulates all the information in the
container.xml
file.
container
REQUIRED root element [xml] of the
container.xml
file.
version
[required]
1.0
".In this order:
The rootfiles
element contains a list of package documents available
in the EPUB container.
Each rootfile
element identifies the location of one package document in the EPUB container.
rootfile
As child of the
element. Repeatable.rootfiles
full-path
[required]
Identifies the location of a package document.
The value of the attribute MUST be a path-relative-scheme-less-URL string [url]. The path is relative to the root directory.
media-type
[required]
Identifies the media type of the package document.
The value of the attribute MUST be
"application/oebps-package+xml
".
Empty
If an EPUB creator defines more than one rootfile
element, each MUST
reference a package document that conforms to the same version of EPUB. Each package
document represents one rendering of the EPUB publication.
Although the EPUB container provides the ability to reference more than one package document, this specification does not define how to interpret, or select from, the available options. Refer to [epub-multi-rend-11] for more information on how to bundle more than one rendering of the content.
The links
element identifies resources
necessary for the processing of the OCF ZIP container.
links
OPTIONAL second child of
. Repeatable.container
None
link
[1 or more]This specification currently does not define uses for the links
element. Refer to [epub-multi-rend-11] for an example of its use.
link
As child of the
element. Repeatable.links
href
[required]
Identifies the location of a resource.
The value of the link
element href
attribute MUST be a path-relative-scheme-less-URL string
[url]. The path is relative to the root directory.
media-type
[optional]
Identifies the type and format of the referenced resource.
The value of the attribute MUST be a media type [rfc2046].
rel
[required]
Identifies the relationship of the resource.
The value of the attribute MUST be a space-separated list of tokens.
Empty
This section is non-normative.
The OPTIONAL encryption.xml
file in the META-INF
directory
holds all encryption information on the contents of the container. If an EPUB creator encrypts any resources within the container, they MUST include an
encryption.xml
file to provide information about the encryption
used.
encryption
urn:oasis:names:tc:opendocument:xmlns:container
REQUIRED root element [xml] of the
encryption.xml
file.
None
In any order:
EncryptedKey
[1 or more]EncryptedData
[1 or more]The encryption
element contains child elements of type
EncryptedKey
and EncryptedData
as defined by
[xmlenc-core1].
An EncryptedKey
element describes each encryption key used
in the container, while an EncryptedData
element describes each
encrypted file. Each EncryptedData
element refers to an
EncryptedKey
element, as described in XML Encryption.
An XML Schema also informally
defines the content of the encryption.xml
file.
OCF encrypts individual files independently, trading off some security for improved performance, allowing the container contents to be incrementally decrypted. Encryption in this way exposes the directory structure and file naming of the whole package.
OCF uses XML Encryption [xmlenc-core1] to provide a framework for encryption,
allowing a variety of algorithms to be used. XML Encryption specifies a process for
encrypting arbitrary data and representing the result in XML. Even though an OCF abstract container may contain non-XML data, EPUB creators can use XML
Encryption to encrypt all data in an OCF abstract container. OCF encryption
supports only the encryption of entire files within the container, not parts of
files. EPUB creators MUST NOT encrypt the encryption.xml
file when
present.
Encrypted data replaces unencrypted data in an OCF abstract container. For example,
if an EPUB creator encrypts an image named photo.jpeg
, they should
replace the contents of the photo.jpeg
resource with its encrypted
contents. Within the ZIP directory, EPUB creators SHOULD store encrypted files
rather than Deflate-compress them.
Note that some situations require obfuscating the storage
of embedded fonts referenced by an EPUB publication to make them more difficult
to extract for unrestricted use. Although obfuscation is not encryption, reading
systems use the encryption.xml
file in conjunction with the font obfuscation algorithm to identify fonts to
deobfuscate.
EPUB creators MUST NOT encrypt the following files:
mimetype
META-INF/container.xml
META-INF/encryption.xml
META-INF/manifest.xml
META-INF/metadata.xml
META-INF/rights.xml
META-INF/signatures.xml
package document
=] EPUB creators MAY subsequently encrypt signed resources using the Decryption Transform for XML Signature [xmlenc-decrypt]. This feature enables a reading system to distinguish data encrypted before signing from data encrypted after signing.
When stored in an OCF ZIP container, EPUB creators SHOULD compress streams of data with non-codec content types before encrypting them. EPUB creators MUST use Deflate compression. This practice ensures that file entries stored in the ZIP container have a smaller size.
EPUB creators SHOULD NOT compress streams of data with codec content types before encrypting them. In such cases, additional compression introduces unnecessary processing overhead at production time (especially with large resource files) and impacts audio/video playback performance at consumption time. In some cases, the combination of compression with some encryption schemes might even compromise the ability of reading systems to handle partial content requests (e.g. HTTP byte ranges), due to the technical impossibility to determine the length of the full resource ahead of media playback (e.g. HTTP Content-Length header).
When EPUB creators compress streams of data before encrypting, they SHOULD provide
additional EncryptionProperties
metadata to specify the size of the
initial resource (i.e., before compression and encryption), as per the
Compression
XML element defined below. When EPUB creators do not
compress streams of data before encrypting, they MAY provide the additional
EncryptionProperties
metadata to specify the size of the initial
resource (i.e., before encryption).
Compression
http://www.idpf.org/2016/encryption#compression
OPTIONAL child of EncryptionProperty
.
[required]
Identifies the compression method used.
Value is either "0
" (no compression) or "8
"
(Deflate algorithm).
[required]
Represents the size of the initial resource (number of bytes).
Value is a positive integer.
Empty
The OPTIONAL manifest.xml
file in the META-INF
directory
provides a manifest of files in the container.
The OCF specification does not mandate a format for the manifest.
Note that package documents specify the only manifests used for processing EPUB publications. Reading systems do not use this file.
The OPTIONAL metadata.xml
file in the META-INF
directory is
only for container-level metadata.
If EPUB creators include a metadata.xml
file, they SHOULD use only
namespace-qualified elements [xml-names] in it. The file SHOULD contain the root element [xml] metadata
in the
namespace http://www.idpf.org/2013/metadata
, but this specification allows
other root elements for backwards compatibility.
This version of the specification does not define metadata for use in the
metadata.xml
file. Future versions of this specification MAY define
container-level metadata.
This specification reserves the OPTIONAL rights.xml
file in the
META-INF
directory for the trusted exchange of EPUB publications
among rights holders, intermediaries, and users.
When EPUB creators do not include a rights.xml
file, no part of the
OCF abstract container is rights governed at the container level. Rights expressions
might exist within the EPUB publications.
Adding a digital signature is not a guarantee that a malicious actor cannot tamper with an EPUB publication as reading systems do not have to check signatures.
The OPTIONAL signatures.xml
file in the META-INF
directory
holds digital signatures for the container and its contents.
signatures
urn:oasis:names:tc:opendocument:xmlns:container
REQUIRED root element [xml] of the
signature.xml
file.
None
Signature
[1 or more]The signature
element contains child elements of type
Signature
, as defined by [xmldsig-core1]. EPUB creators can
apply signatures to an EPUB publication as a whole or to its parts, and can specify
the signing of any kind of data (i.e., not just XML).
An XML Schema also informally
defines the content of the signatures.xml
file.
When an EPUB creator does not include a signatures.xml
file, they are
not signing any part of the OCF abstract container at the container level.
Digital signing might exist within the EPUB publication.
When an EPUB creator creates a data signature for the OCF abstact
container, they SHOULD add the signature as the last child Signature
element of the signatures
element.
Each Signature
in the signatures.xml
file identifies by
URL [url] the data to which the signature applies, using the [xmldsig-core1]
Manifest
element and its Reference
sub-elements.
EPUB creator may sign individual container files separately or together.
Separately signing each file creates a digest value for the resource that
reading systems can validate independently. This approach might make a Signature
element larger. If EPUB creators sign files together, they can list the set of
signed files in a single XML Signature Manifest
element and
reference them by one or more Signature
elements.
EPUB creators can sign any or all files in the OCF abstract
container in their entirety, except for the signatures.xml
file since
that file will contain the computed signature information. Whether and how EPUB
creators sign the signatures.xml
file depends on their objective.
If the EPUB creator wants to allow signatures to be added or removed from the OCF
abstract container without invalidating their signature, they SHOULD NOT sign the
signatures.xml
file.
If the EPUB creator wants any addition or removal of a signature to invalidate their
signature, they can use the Enveloped Signature transform defined in Section 6.6.4 of
[xmldsig-core1] to sign the entire pre-existing signature file excluding the
Signature
being created. This transform would sign all previous
signatures, and it would become invalid if a subsequent signature were added to the
package.
If the EPUB creator wants the removal of an existing signature to invalidate their signature, but also wants to allow the addition of signatures, they could use an XPath transform to sign just the existing signatures. The details of such a transform are outside the scope of this specification, however.
The [xmldsig-core1] specification does not associate any semantics with a
signature; an agent might include semantic information, for example, by adding
information to the Signature element that describes the signature. The
[xmldsig-core1] specification describes how additional information can be added to
a signature, such as by use the SignatureProperties
element.
This section is non-normative.
An OCF ZIP container is a physical single-file manifestation of an OCF abstract container. The container allows:
the exchange of in-progress EPUB publication between different individuals and/or different organizations;
the transfer of EPUB publications from a publisher or conversion house to the distribution or sales channel; and
the delivery of EPUB publications to EPUB reading systems or users.
An OCF ZIP container uses the ZIP format as specified by [zip], but with the following constraints and clarifications:
The contents of the OCF ZIP container MUST be a conforming OCF abstract container.
OCF ZIP containers MUST NOT use the features in the ZIP application note [zip] that allow ZIP files to be spanned across multiple storage media or be split into multiple files.
OCF ZIP containers MUST include only stored (uncompressed) and Deflate-compressed ZIP entries within the ZIP archive.
OCF ZIP containers MAY use the ZIP64 extensions defined as "Version 1" in section V, subsection G of the application note [zip] and SHOULD use only those extensions when the content requires them.
OCF ZIP containers MUST NOT use the encryption features defined by
the ZIP format; instead, encryption MUST be done using the features described in 4.2.6.3.2 Encryption file (encryption.xml
).
OCF ZIP containers MUST encode file system names using UTF-8 [unicode].
The following constraints apply to specific fields in the OCF ZIP container archive:
In the local file header table, EPUB creators MUST set
the version needed to extract
fields to the values 10
,
20
or 45
to match the maximum version level needed by the
given file (e.g., 20
for Deflate, 45
for ZIP64).
In the local file header table, EPUB creators MUST set the
compression
method field to the values 0
or
8
.
EPUB creators MUST include the mimetype
file as the first file in the OCF ZIP container. In addition:
mimetype
file MUST be the MIME media type [rfc2046]
string application/epub+zip
encoded in US-ASCII [us-ascii].mimetype
file MUST NOT contain any leading or trailing padding or white
space.mimetype
file MUST NOT begin with the Unicode byte order mark U+FEFF.mimetype
file.Refer to I.2 The application/epub+zip
media type for further information about the
application/epub+zip
media type.
Better methods of protecting fonts exist. Both [woff] and [woff2] fonts, for example, allow the embedding of licensing information and provide some protection through font table compression. The use of remotely hosted fonts also allows for font subsetting. EPUB creators are advised to use font obfuscation as defined in this section only when no other options are available to them. See also the limitations of obfuscation.
This section is non-normative.
Since an OCF ZIP container is fundamentally a ZIP file, commonly available ZIP tools can be used to extract any unencrypted content stream from the package. Moreover, the nature of ZIP files means that their contents might appear like any other native container on some systems (e.g., a folder).
While this simplicity of ZIP files is quite useful, it also poses a problem when ease of extraction of fonts is not a desired side-effect of not encrypting them. An EPUB creator who wishes to include a third-party font, for example, typically does not want that font extracted and re-used by others. More critically, many commercial fonts allow embedding, but embedding a font implies making it an integral part of the EPUB publication, not just providing the original font file along with the content.
Since integrated ZIP support is so ubiquitous in modern operating systems, simply placing a font in the OCF ZIP container is insufficient to signify that the font cannot be reused in other contexts. This uncertainty can undermine the otherwise useful font embedding capability of EPUB publications.
To discourage reuse of their fonts, some font vendors might only allow their use in EPUB publications if the fonts are bound in some way to the EPUB publication. That is, if the font file cannot be installed directly for use on an operating system with the built-in tools of that computing device, and it cannot be directly used by other EPUB publications.
It is beyond the scope of this specification to provide a digital rights management or enforcement system for fonts. This section instead defines a method of obfuscation that will require additional work on the part of the final OCF recipient to gain general access to any obfuscated fonts.
This section is non-normative.
This specification does not claim that obfuscation constitutes encryption, nor does it guarantee that the resource will be secure from copyright infringement. The hope is only that this algorithm will meet the requirements of vendors who require some assurance that their fonts cannot be extracted simply by unzipping the OCF ZIP container and copying the resource.
Obfuscation, like any protection scheme, cannot fully protect fonts from being accessed in their deobfuscated state. The mechanism only provides an obstacle for those who are unaware of the license details. It will not prevent a determined user from gaining full access to the font through such alternative means as:
As a result, whether this method of obfuscation satisfies the requirements of individual font licenses remains a question for the licensor and licensee. EPUB creators are responsible for ensuring their use of obfuscation meets font licensing requirements.
EPUB creators should also be aware that obfuscation may lead to interoperability issues in reading systems as reading systems are not required to deobfuscate fonts. As a result, the visual presentation of their publications may differ from reading system to reading system.
Also note that the algorithm is restricted to obfuscating fonts. It is not intended as a general-purpose mechanism for obfuscating any resource in the EPUB container.
EPUB creators MUST derive the key used in the obfuscation algorithm from the unique identifier.
All white space characters, as defined in section 2.3 of the
XML 1.0 specification [xml], MUST be removed from this identifier — specifically, the
Unicode code points U+0020
, U+0009
, U+000D
and
U+000A
.
EPUB creators MUST generate a SHA-1 digest of the UTF-8 representation of the resulting string as specified by the Secure Hash Standard [fips-180-4]. They can then use this digest as the key for the algorithm.
The algorithm employed to obfuscate fonts consists of modifying the first 1040 bytes (~1KB) of the font file. (In the unlikely event that the font file is less than 1040 bytes, this process will modify the entire file.)
To obfuscate the original data, store, as the first byte of the embedded font, the result of performing a logical exclusive or (XOR) on the first byte of the raw font file and the first byte of the obfuscation key.
Repeat this process with the next byte of source and key and continue for all bytes in the key. At this point, the process continues starting with the first byte of the key and 21st byte of the source. Once 1040 bytes are encoded in this way (or the end of the source is reached), directly copy any remaining data in the source to the destination.
EPUB creators MUST obfuscate fonts before compressing and adding them to the OCF ZIP container. Note that as obfuscation is not encryption, this requirement is not a violation of
the one in 4.2.6.3.2 Encryption file (encryption.xml
) to compress fonts before
encrypting them.
The following pseudo-code exemplifies the obfuscation algorithm.
Although not technically encrypted data, all obfuscated fonts MUST have an entry in the encryption.xml
file accompanying the EPUB publication (see 4.2.6.3.2 Encryption file (encryption.xml
)).
EPUB creators MUST specify an EncryptedData
element for each obfuscated font.
Each EncryptedData
element MUST contain a child EncryptionMethod
element whose Algorithm
attribute has the value
http://www.idpf.org/2008/embedding
. The presence of this attribute signals the
use of the algorithm described in this specification.
EPUB creators MUST list the path to the obfuscated font in the CipherReference
child
of the CipherData
element. As the obfuscation algorithm is restricted to fonts, the
URI
attribute of the CipherReference
element MUST reference a Font core media type resource.
To prevent trivial copying of the embedded font to other EPUB publications, EPUB creators MUST NOT provide the obfuscation key in the encryption.xml
file.
All [xml] elements defined in this section are in the http://www.idpf.org/2007/opf
namespace [xml-names] unless otherwise specified.
This section is non-normative.
The package document is an XML document that consists of a set of elements that each encapsulate information about a particular aspect of an EPUB publication. These elements serve to centralize metadata, detail the individual resources, and provide the reading order and other information necessary for its rendering.
The following list summarizes the information found in the package document:
Metadata — mechanisms to include and/or reference information about the EPUB publication.
A manifest — identifies via URL [url], and describes via MIME media type [rfc4839], the set of publication resources.
A spine — an ordered sequence of ID references to top-level resources in the manifest from which reading systems can reach or utilize all other resources in the set. The spine defines the default reading order.
Collections — a method of encapsulating and identifying subcomponents within the EPUB publication.
Manifest fallback chains — a mechanism that defines an ordered list of top-level resources as content equivalents. A reading system can then choose between the resources based on which it is capable of rendering.
An EPUB publication can reference more than one package document, allowing for alternative
representations of the content. For more information, refer to 4.2.6.3.1 Container file (container.xml
)
Refer to I.1 The application/oebps-package+xml
media type for information about the file
properties of package documents.
To parse a URL string url used in the package document, the URL parser [url] MUST be applied to url, with the content URL of the package document as base.
The package
element encapsulates all the information expressed in the package document.
package
REQUIRED root element [xml] of the package document.
In this order:
metadata
[exactly 1]
manifest
[exactly 1]
spine
[exactly 1]
bindings
[0 or 1]
(deprecated)
collection
[0 or more]
The version
attribute specifies the EPUB specification
version to which the given EPUB publication conforms. The attribute MUST have the value
"3.0
" to indicate conformance with EPUB 3.
Updates to this specification do not represent new versions of EPUB 3 (i.e., each new 3.X
specification is a continuation of the EPUB 3 format). The Working Group is committed to
minimizing any changes that would invalidate existing content, allowing the version
attribute value to remain unchanged.
The unique-identifier
attribute takes an IDREF
[xml] that identifies the
element that provides the preferred, or primary,
identifier.dc:identifier
The prefix
attribute provides a declaration mechanism for
prefixes not reserved by this specification. Refer to
D.1.4 The prefix
attribute for more information.
The metadata
element encapsulates meta information.
metadata
REQUIRED first child of
.package
None
In any order:
dc:identifier
[1 or more]
dc:title
[1 or more]
dc:language
[1 or more]
Dublin Core Optional Elements
[0 or more]
meta
[1 or more]
link
[0 or more]
The package document metadata
element has two primary functions:
to provide a minimal set of meta information for reading systems to use to internally catalogue an EPUB publication and make it available to a user (e.g., to present in a bookshelf).
to provide access to all rendering metadata needed to control the layout and display of the content (e.g., fixed-layout properties).
The package document does not provide complex metadata encoding capabilities. If EPUB creators need to provide more detailed information, they can associate metadata records (e.g.,
that conform to an international standard such as [onix] or are created for custom purposes)
using the
element. This approach allows reading systems to process the metadata in its
native form, avoiding the potential problems and information loss caused by translating to use
the minimal package document structure.link
In keeping with this philosophy, the package document only has the
following minimal metadata requirements: it MUST contain the [dcterms]
,
dc:title
, and dc:identifier
elements together with the [dcterms]
dc:language
property. All other metadata is OPTIONAL.dcterms:modified
The
element provides a generic mechanism for including metadata properties from any vocabulary. Although EPUB creators MAY use this mechanism
for any metadata purposes, they will typically use it to include rendering metadata defined in
EPUB specifications.meta
See [epub-a11y-11] for accessibility metadata recommendations.
The Dublin Core elements [dcterms] and
element have mandatory child text content
[dom]. In the descriptions for these elements, this specification refers to this content as
the element's value.meta
These elements MUST have non-empty values after leading and trailing ASCII whitespace [infra] is stripped (i.e., they must consist of at least one non-whitespace character).
Whitespace within these element values is not significant. Sequences of one or more whitespace characters are collapsed to a single space [infra] during processing .
The dc:identifier
element [dcterms] contains an identifier such as a UUID, DOI or ISBN.
dc:identifier
http://purl.org/dc/elements/1.1/
REQUIRED child of
. Repeatable.metadata
id
[conditionally required]
Text
The EPUB creator MUST provide an identifier that is unique to one and only one EPUB publication — its unique identifier — in an dc:identifier
element. This
dc:identifier
element MUST specify an id
attribute whose value
is referenced from the
element's package
unique-identifier
attribute.
Although not static, EPUB creators should make changes to the unique identifier for an EPUB publication as infrequently as possible. Unique Identifiers should have maximal persistence both for referencing and distribution purposes. EPUB creators should not issue new identifiers when making minor revisions such as updating metadata, fixing errata, or making similar minor changes.
EPUB creators MAY specify additional identifiers. The identifiers should be fully qualified URIs.
EPUB creators MAY use the identifier-type
property to indicate that the value of a dc:identifier
element conforms
to an established system or an issuing authority granted it.
The dc:title
element [dcterms] represents an instance of a name for the EPUB publication.
dc:title
http://purl.org/dc/elements/1.1/
REQUIRED child of
. Repeatable.metadata
Text
The first dc:title
element in document order is the main title
of the EPUB publication (i.e., the primary one reading systems present to users).
EPUB creators should use only a single dc:title
element to ensure consistent
rendering of the title in reading systems.
Although it is possible to include more than one dc:title
element for
multipart titles, reading system support for additional dc:title
elements
is inconsistent. Reading systems may ignore the additional segments or combine them in
unexpected ways.
For example, the following example shows a basic multipart title:
<metadata …>
<dc:title>
THE LORD OF THE RINGS
</dc:title>
<dc:title>
Part One: The Fellowship of the Ring
</dc:title>
…
</metadata>
The same title could instead be expressed using a single dc:title
element as
follows:
<metadata …>
<dc:title>
THE LORD OF THE RINGS, Part One:
The Fellowship of the Ring
</dc:title>
…
</metadata>
Previous versions of this specification recommended using the title-type
and display-seq
properties to identify and format the segments of
multipart titles (see the Great Cookbooks example). It is
still possible to add these semantics, but they are also not well supported.
The dc:language
element [dcterms] specifies the language of the content of the
EPUB publication.
dc:language
http://purl.org/dc/elements/1.1/
REQUIRED child of
. Repeatable.metadata
id
[optional]
Text
The value of each dc:language
element MUST be a well-formed language tag [bcp47].
Although EPUB creators MAY specify additional dc:language
elements for
multilingual Publications, reading systems will treat the first dc:language
element in document order as the primary language of the EPUB publication.
Publication resources do not inherit their language from the dc:language
element(s). EPUB creators must set the language of a resource using the intrinsic
methods of the format.
All [dcterms] elements except for
, dc:identifier
, and dc:language
are
designated as OPTIONAL. These elements conform to the following generalized definition:dc:title
dc:contributor
| dc:coverage
| dc:creator
|
dc:date
| dc:description
| dc:format
|
dc:publisher
| dc:relation
| dc:rights
|
dc:source
| dc:subject
| dc:type
http://purl.org/dc/elements/1.1/
OPTIONAL child of
. Repeatable.metadata
dir
[optional]
– only allowed on dc:contributor
,
dc:coverage
, dc:creator
,
dc:description
, dc:publisher
,
dc:relation
, dc:rights
, and
dc:subject
.
id
[optional]
– allowed on any element.
xml:lang
[optional]
– only allowed on dc:contributor
,
dc:coverage
, dc:creator
,
dc:description
, dc:publisher
,
dc:relation
, dc:rights
, and
dc:subject
.
Text
This specification does not modify the [dcterms] element definitions except as noted in the following sections.
The dc:contributor
element [dcterms] is used to represent the name
of a person, organization, etc. that played a secondary role in the creation of the
content.
The requirements for the dc:contributor
element are identical to those for the
element in all other respects.dc:creator
The dc:creator
element [dcterms] represents the name of a person,
organization, etc. responsible for the creation of the content. EPUB creators MAY associate a role
property
with the element to indicate the function the creator played.
The dc:creator
element should contain the name of the creator as EPUB creators
intend reading systems to display it to users.
EPUB creators MAY use the file-as
property
to associate a normalized form of the creator's name, and the
alternate-script
property to represent the
creator's name in another language or script.
If an EPUB publication has more than one creator, EPUB creators should specify each in a
separate dc:creator
element.
The document order of dc:creator
elements in the metadata
section
determines the display priority, where the first dc:creator
element encountered
is the primary creator.
EPUB creators should represent secondary contributors using the
element.dc:contributor
The dc:date
element [dcterms] defines the publication date of the
EPUB publication. The publication date is not the same as the last modified date (the last time the EPUB creator
changed the EPUB publication).
It is RECOMMENDED that the date string conform to [iso8601], particularly the subset expressed in W3C Date and Time Formats [datetime], as such strings are both human and machine readable.
EPUB creators should express additional dates using the specialized date properties available in the [dcterms] vocabulary, or similar.
EPUB publications MUST NOT contain more than one dc:date
element.
The dc:subject
element [dcterms] identifies the subject of the EPUB publication. EPUB creators should set the value of the element to the
human-readable heading or label, but may use a code value if the subject taxonomy does not
provide a separate descriptive label.
EPUB creators MAY identify the system or scheme they drew the element's value from using
the authority
property.
When a scheme is identified, EPUB creators MUST associate a
subject code using the term
property.
The term
property MUST NOT be associated with a
dc:subject
element that does not specify a scheme.
The values of the dc:subject
element and term
property are case
sensitive only when the designated scheme requires.
The dc:type
element [dcterms] is used to indicate that the EPUB publication is of a specialized type (e.g., annotations or a dictionary packaged in EPUB
format).
EPUB creators MAY use any text string as a value.
The former IDPF EPUB 3 Working Group maintained a non-normative registry of specialized EPUB publication types for use with this element. This Working Group no longer maintains the registry and does not anticipate developing new specialized publication types.
The meta
element provides a generic means of including package metadata.
meta
As child of the
element. Repeatable.metadata
Text
Each meta
element defines a metadata expression. The
property
attribute takes a property
data type value that defines the statement made in the expression, and the text content
of the element represents the assertion. (Refer to D.1 Vocabulary association mechanisms for more
information.)
This specification defines two types of metadata expressions that EPUB creators can define using the meta
element:
meta
element establishes some aspect of the EPUB publication. A
meta
element that omits a refines attribute defines a primary
expression.meta
element is associated with another expression or resource using the
refines
attribute to enhance its meaning. A subexpression might refine a
media clip, for example, by expressing its duration, or refine a creator or contributor
expression by defining the role of the person.EPUB creators MAY use subexpressions to refine the meaning of other subexpressions, thereby creating chains of information.
All the [dcterms] elements represent primary expressions, and permit refinement by meta element subexpressions.
The Meta Properties Vocabulary is the default vocabulary for use with the property
attribute.
EPUB creators MAY add terms from other vocabularies as defined in D.1 Vocabulary association mechanisms.
The scheme
attribute identifies the system or scheme the EPUB
creator obtained the element's value from. The value of the attribute MUST be a property data type value that resolves to the
resource that defines the scheme. The scheme
attribute does not have a default vocabulary (i.e., all values require a prefix).
The metadata
section MUST contain exactly one dcterms:modified
property [dcterms]
containing the last modification date. The value of this property MUST be an [xmlschema-2]
dateTime conformant date of the form: CCYY-MM-DDThh:mm:ssZ
EPUB creators MUST express the last modification date in Coordinated Universal Time (UTC) and
MUST terminate it with the "Z
" (Zulu) time zone indicator.
EPUB creators should update the last modified date whenever they make changes to the EPUB publication.
EPUB creators MAY specify additional modified properties in the package document metadata,
but they MUST have a different subject (i.e., they require a refines
attribute that
references an element or resource).
The requirements for the last modification date are to ensure compatibility with earlier versions of EPUB 3 that defined a release identifier [epubpackages-32] for EPUB publications.
The link
element associates resources with an EPUB publication, such as metadata
records.
link
As a child of
. Repeatable.metadata
href
[required]
hreflang
[optional]
id
[optional]
media-type
[conditionally required]
properties
[optional]
refines
[optional]
rel
[required]
Empty
The
element MAY contain zero or more metadata
link
elements, each of which
identifies the location of a publication resource or a linked resource in its REQUIRED
href
attribute.
Resources referenced from the link
element are
publication resources only when they are:
referenced from the spine; or
included or embedded in an EPUB content document (e.g., a metadata record serialized
as RDFa [rdfa-core] or as JSON-LD [json-ld11] embedded in an
[html] script
element).
In all other cases (e.g., when linking to standalone [onix] records), the resources referenced are not publication resources (i.e., are not subject to core media type requirements) and EPUB creators MUST NOT list them in the manifest.
EPUB creators MAY locate linked resources within the EPUB container or externally, but should consider that reading systems are not required to retrieve resources outside the EPUB container.
The media-type
attribute is OPTIONAL when a linked resource is located outside the EPUB container, as
more than one media type could be served from the same URL [url]. EPUB creators MUST specify
the attribute for all linked resources within the EPUB container.
The OPTIONAL hreflang
attribute identifies the language of the
linked resource. The value MUST be a well-formed language
tag [bcp47].
The REQUIRED rel
attribute takes a space-separated list of property values that establish the relationship the linked
resource has with the EPUB publication.
The value of the media-type
attribute is not always sufficient to identify the type
of linked resource (e.g., many XML-based record formats use the media type
"application/xml
"). To aid reading systems in the identification of such
generic resources, EPUB creators MAY specify a semantic identifier in the
properties
attribute.
The Metadata Link Vocabulary is the default vocabulary for the rel
and properties
attributes.
EPUB creators MAY add relationships and properties from other vocabularies as defined in D.1 Vocabulary association mechanisms.
EPUB creators MAY provide one or more linked metadata records.
Due to the variety of metadata record formats and serializations that an EPUB creator can link to an EPUB publication, and the complexity of comparing metadata properties between them, this specification does not require reading systems to process linked records.
In addition to full records, EPUB creators MAY also use the link
element to identify
individual metadata properties available in an alternative format.
The manifest
element provides an exhaustive list of publication resources used
in the rendering of the content.
With the exception of the package document, the
manifest
MUST list all publication resources regardless of whether they are
container resources or remote resources.
As the package document is already identified by the container.xml
file, the
manifest
MUST NOT specify an item
element for it (i.e., a
self-reference serves no purpose).
The manifest is only for listing publication resources. Linked resources and the special files for processing the OCF
Container (i.e., files in the META-INF
directory, and the
mimetype
file) are restricted from inclusion.
Failure to provide a complete manifest of publication resources may lead to rendering issues. Reading systems might not unzip such resources or could prevent access to them for security reasons.
The item
element represents a publication resource.
item
As a child of
. Repeatable.manifest
fallback
[conditionally required]
href
[required]
id
[required]
media-overlay
[optional]
media-type
[required]
properties
[optional]
Empty
Each item
element identifies a publication resource by the
URL [url] in its href
attribute. The value MUST be an
absolute- or path-relative-scheme-less-URL
string [url]. EPUB creators MUST ensure each URL is unique within the
manifest
scope after parsing.
The publication resource identified by an item
element
MUST conform to the applicable specification(s) as inferred from the MIME media type [rfc2046]
provided in the media-type
attribute. For core media type resources, EPUB creators MUST use the media type designated in 3.2 Core media types.
The fallback
attribute specifies the fallback for the
referenced publication resource. The fallback
attribute's IDREF [xml] value MUST resolve to another item
in the
manifest
.
The fallback for one item
MAY specify a fallback to another item
, and
so on, creating a chain of fallback options. Refer to 3.5.1 Manifest fallbacks for
additional requirements related to the use of fallback chains.
The media-overlay
attribute takes an IDREF [xml]
that identifies the media overlay document for the resource described by this
item
. Refer to 9.3.5 Media overlays packaging for more information.
The order of item
elements in the manifest
is not significant. The
element provides the presentation sequence of content documents.spine
The properties
attribute provides information
to reading systems about the content of a resource. This information enables discovery
of key resources, such as the cover image and EPUB navigation document. It also allows
reading systems to optimize rendering by indicating, for example, whether the resource
contains embedded scripting, MathML, or SVG.
The Manifest Properties
Vocabulary is the default vocabulary for the
properties
attribute.
EPUB creators MUST set the following properties whenever a resource referenced by an
item
element matches their respective definitions:
These properties do not apply recursively to content included into a resource (e.g., via the
[html] iframe
element). For example, if a non-scripted XHTML content document
embeds a scripted content document, only the embedded document's manifest
item
properties
attribute will have the scripted
value.
EPUB creators MUST declare exactly one item
as the EPUB navigation document
using the nav
property.
If an EPUB publication contains a cover image, it is recommended to set the cover-image
property, but setting this property
is OPTIONAL.
EPUB creators MAY add terms from other vocabularies as defined in D.1 Vocabulary association mechanisms.
The bindings
element defines a set of custom handlers for media types not supported
by this specification.
Use of the element is deprecated.
Refer to the bindings
element definition in [epubpublications-301] for more
information.
The spine
element defines an ordered list of manifest
item
references that represent the default reading order.
spine
id
[optional]
page-progression-direction
[optional]
itemref
[1 or more]
The spine
MUST specify at least one EPUB content document or foreign content document.
EPUB creators MUST list in the spine
all EPUB and
foreign content documents that are hyperlinked to from publication resources in the
spine
, where hyperlinking encompasses any linking mechanism that requires the
user to navigate away from the current resource. Common hyperlinking mechanisms include the
href
attribute of the [html] a
and area
elements and scripted links (e.g., using
DOM Events and/or form elements). The requirement to list hyperlinked resources applies
recursively (i.e., EPUB creators must list all EPUB and foreign content documents hyperlinked to
from hyperlinked documents, and so on.).
EPUB creators also MUST list in the spine
all EPUB and foreign content documents
hyperlinked to from the EPUB navigation document, regardless of whether EPUB creators
include the EPUB navigation document in the spine
.
As hyperlinks to resources outside the EPUB container are not publication resources, they are not subject to the requirement to include in the spine (e.g., web pages and web-hosted resources).
Publication resources used in the rendering of spine items (e.g., referenced from [html] embedded content) similarly do not have to be included in the spine.
The page-progression-direction
attribute sets the global direction in which the content flows. Allowed values are
ltr
(left-to-right), rtl
(right-to-left) and default
.
When EPUB creators specify the default
value, they are expressing no preference and
the reading system can choose the rendering direction.
Although the page-progression-direction
attribute sets the global flow direction,
individual EPUB content documents and parts of EPUB content documents MAY override this setting
(e.g., via the writing-mode
CSS property). Reading systems may also provide
mechanisms to override the default direction (e.g., buttons or settings that allow the
application of alternate style sheets).
The legacy
toc
attribute takes an IDREF [xml] that identifies
the manifest item that represents the NCX.
The itemref
element identifies an EPUB content document or foreign content document in the default reading order.
itemref
As a child of
. Repeatable.spine
id
[optional]
idref
[required]
linear
[optional]
properties
[optional]
Empty
Each itemref
element MUST reference the ID [xml] of an
in the manifest via the
IDREF [xml] in its item
idref
attribute.
item
element IDs MUST NOT be referenced more than once.
Each referenced manifest item
MUST be either a) an
EPUB content document or b) a foreign content document that includes an EPUB content
document in its manifest fallback chain.
Although EPUB publications require an EPUB navigation document, it is not mandatory to include it in the spine.
The linear
attribute indicates whether the referenced
item
contains content that contributes to the primary reading order and that
reading systems must read sequentially ("yes
"), or auxiliary content that
enhances or augments the primary content that reading systems can access out of sequence
("no
"). Examples of auxiliary content include notes, descriptions, and answer
keys.
The linear
attribute allows reading systems to distinguish content that a user
should access as part of the default reading order from supplementary content which a reading
system might, for example, present in a popup window or omit from an aural rendering.
Specifying that content is non-linear does not require reading systems to present it in a specific way, however; it is only a hint to the purpose. Reading systems may present non-linear content where it occurs in the spine, for example, or may skip it until users reach the end of the spine.
EPUB creators should list non-linear content at the end of the spine except when it makes sense for users to encounter it between linear spine items.
A linear itemref
element is one whose linear
attribute value is explicitly set to "yes
" or that omits the
attribute — reading systems will assume the value "yes
" for
itemref
elements without the attribute. The spine MUST contain at least one
linear itemref
element.
EPUB creators MUST provide a means of accessing all non-linear content (e.g., hyperlinks in the content or from the EPUB navigation document).
The Spine Properties
Vocabulary is the default vocabulary for the
properties
attribute.
EPUB creators MAY add terms from other vocabularies as defined in D.1 Vocabulary association mechanisms.
The collection
element defines a related group of resources.
collection
OPTIONAL sixth element of package
. Repeatable.
In this order: metadata
[0 or 1]
, ( collection
[1 or more]
or ( collection
[0 or more]
, link
[1 or more]
))
The collection
element allows EPUB creators to assemble resources into logical
groups for a variety of potential uses: enabling reassembly into a meaningful unit of content
split across multiple EPUB content documents (e.g., an index split across multiple
documents), identifying resources for specialized purposes (e.g., preview content), or
collecting together resources that present additional information about the EPUB publication.
EPUB creators MUST identify the role of each collection
element in its role
attribute, whose value MUST be one or more NMTOKENs
[xmlschema-2] and/or absolute-URL-with-fragment strings [url].
The requirements for authoring specialized collections are defined by their respective specifications.
The former IDPF EPUB 3 Working Group maintained both a registry of role extensions and a list of custom extension roles. This Working Group no longer maintains these registries.
The creation of new collection
element roles is now deprecated.
Refer to the collection
element definition in [epubpackages-32] for more
information about the creation of specialized collections, including the requirements and
restrictions on their use.
The package document legacy features are retained from EPUB 2 only to allow EPUB creators to author content that can function, to some degree, in reading systems that only support EPUB 2 publications.
These features were added primarily to address the overlap period as EPUB 3 reading systems were developed, as there was still a high probability at that time that users would be opening EPUB 3 publications on EPUB 2 reading systems.
As reading systems that only handle EPUB 2 publications are now rare, EPUB creators should consider the likelihood of their publications still being opened on these types of older devices before making the effort to add these legacy features.
EPUB creators MAY include the legacy features defined in this section for compatibility purposes with EPUB 2 reading systems.
EPUB 3 reading systems will not use these features when presenting publications to users.
EPUB conformance checkers should not alert EPUB creators about the presence of legacy features in an EPUB publication, as their inclusion is valid for backwards compatibility. EPUB conformance checkers must alert EPUB creators if a legacy feature does not conform to its definition or otherwise breaks a usage requirement.
The meta
element [opf-201] provides a means of including generic metadata for EPUB 2 reading systems.
Refer to the meta
element definition in [opf-201] for more information.
The EPUB 3
element, which uses different attributes and requires text content,
provides metadata capabilities for EPUB 3 reading systems.meta
The [opf-201] meta
element also allows EPUB creators to identify a cover
image for EPUB 2 reading systems. In EPUB 3, the cover image must be identified using the cover-image
property on the manifest
for the image.item
The guide
element [opf-201] provides machine-processable navigation to key structures in
EPUB 2 reading systems.
Refer to the guide
element definition in [opf-201] for more information.
The landmarks nav in the EPUB navigation document provides this functionality in EPUB 3 reading systems.
The NCX [opf-201] provides a table of contents for EPUB 2 reading systems.
Refer to the NCX definition in [opf-201] for more information.
The EPUB navigation document replaces the NCX for EPUB 3 reading systems.
This section is non-normative.
This section defines a profile of [html] for creating XHTML content documents. An instance of an XML document that conforms to this profile is a core media type resource and is referred to in this specification as an XHTML content document.
MUST conform to the conformance criteria for all document constructs defined by [html] unless explicitly overridden in 6.1.4 HTML deviations and constraints.
MAY include extensions to the [html] grammar as defined in 6.1.3 HTML extensions, and MUST conform to all content conformance constraints defined therein.
Unless specified otherwise, XHTML content documents inherit all definitions of semantics, structure, and processing behaviors from the [html] specification.
The recommendation that EPUB publications follow the accessibility requirements in [epub-a11y-11] applies to XHTML content documents. See Accessibility.
This section defines EPUB 3 XHTML content document extensions to the underlying [html] document model.
Although [html] allows user agents to support vendor-neutral extensions, unless such extensions are listed in this section, they are not supported features of EPUB 3.
EPUB creators MAY use the
attribute in XHTML content documents to
express structural semantics.epub:type
The attribute MUST NOT be used on the head
element or metadata content [html].
The [html-rdfa] specification defines a set of attributes that EPUB creators MAY use in XHTML content documents to semantically enrich the content. The use of these attributes MUST conform to the requirements defined in [html-rdfa].
The [html-rdfa] specification defines changes to the [html] content model when authors use RDFa attributes. This modified content model is valid in XHTML content documents.
The listing of RDFa does not express a preference on the part of the Working Group, only that these attributes represent an extension of the HTML grammar. EPUB creators can also specify microdata attributes [html] and linked data [json-ld11] in XHTML content documents as both are natively supported.
The switch
element provides a simple mechanism through which EPUB creators
can tailor the content displayed to users, one that is not dependent on the scripting
capabilities of the EPUB reading system.
Use of the element is deprecated.
Refer to the switch
element definition in [epubcontentdocs-301] for more
information.
The trigger
element enables the creation of markup-defined user interfaces for
controlling multimedia objects, such as audio and video playback, in both scripted and
non-scripted contexts.
Use of the element is deprecated.
Refer to the epub:trigger
element definition in [epubcontentdocs-301]
for more information.
XHTML content documents MAY contain custom attributes, which are prefixed [xml-names] attributes whose namespace URL does not include either of the following strings in its domain [url]:
w3.org
idpf.org
When using custom attributes, the content MUST remain consumable by a user without any information loss or other significant deterioration, regardless of the reading system it is rendered on.
Custom attributes are usually defined in a reading system-specific manner and are not intended for use by other reading systems. This specification should be extended to provide extensions that multiple independent reading systems can use.
This section defines deviations from, and constraints on, the underlying [html] document model applicable to EPUB 3 XHTML content documents.
XHTML content documents support embedded [mathml3]. Occurrences of MathML markup MUST conform to the constraints expressed in the MathML specification [mathml3], with the following additional restrictions:
The math
element MUST contain only Presentation MathML, except within the
annotation-xml
element.
EPUB creators MAY include Content MathML within MathML markup in
XHTML content documents, and, when present, MUST include it within an
annotation-xml
child element of a semantics
element.
When EPUB creators include Content MathML per
the previous condition, they MUST set the given annotation-xml
element's encoding
attribute to either of the functionally-equivalent
values MathML-Content
or application/mathml-content+xml
,
and the name
attribute to contentequiv
.
This subset eases the implementation burden on reading systems and promotes accessibility, while retaining compatibility with [html] user agents.
The mathml
property of the manifest item
element indicates that an XHTML content document contains
embedded MathML.
XHTML content documents support the embedding of SVG document
fragments [svg] by reference (embedding via reference, for example, from
an img
or object
element) and by inclusion (embedding via
direct inclusion of the svg
element in the XHTML content document).
The content conformance constraints for SVG embedded in XHTML content documents are the same as defined for SVG content documents in 6.2.3 Restrictions on SVG.
The svg
property of the manifest
element indicates that an XHTML content document contains embedded SVG.item
This section is non-normative.
The [html] base
element can be used to specify the document base URL for the purposes of
parsing URLs. When using it in an EPUB publication, the interpretation of the
base
element may inadvertently result in references to remote resources. It may also cause reading systems to misinterpret the location of
hyperlinks (e.g., relative links to other documents in the publication might appear as
links to a web site if the base
element specifies an absolute URL). To
avoid significant interoperability issues, EPUB creators should not use the
base
element.
The [html] rp
element is intended to provide a fallback
for older reading systems that do not recognize ruby markup (i.e., a parenthesis
display around ruby
markup). As EPUB 3 reading systems are ruby-aware, and
can provide fallbacks, EPUB creators should not use rp
elements.
Since the [html] embed
element element does not include intrinsic facilities to provide fallback
content for reading systems that do not support scripting, EPUB creators are
discouraged from using the element when the referenced resource includes scripting. The
[html] object
element is a better alternative, as it includes intrinsic fallback
capabilities.
Reading systems may not support all the features of [svg] or support them across all platforms that reading systems run on. When utilizing such features, EPUB creators should consider the inherent risks on interoperability and document longevity.
This section is non-normative.
The Scalable Vector Graphics (SVG) specification [svg] defines a format for representing final-form vector graphics and text.
Although EPUB creators typically use XHTML content documents as the top-level document type, the use of SVG content documents is also permitted. EPUB creators will typically only need SVGs for certain special cases, such as when final-form page images are the only suitable representation of the content (e.g., for cover art or 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 a core media type resource and is referred to in this specification as an SVG content document.
This section defines conformance requirements for SVG content documents. Refer to 6.1.4.2 Embedded SVG for the conformance requirements for SVG embedded in XHTML content documents.
MUST be a conforming SVG stand-alone file [svg] and conform to all content conformance constraints expressed in 6.2.3 Restrictions on SVG.
MAY include the
attribute for
expressing structural semantics. When specified,
the attribute MUST only be included on structural,
shape, or text elements [svg].epub:type
MAY include all applicable vocabulary association mechanisms.
The recommendation that EPUB publications follow the accessibility requirements in [epub-a11y-11] applies to SVG content documents. See Accessibility.
This specification restricts the content model of SVG content documents and SVG embedded in XHTML content documents as follows:
The [svg] foreignObject
element:
MUST contain either [html] flow content or exactly one [html] body
element.
In the case of embedded SVGs, a
body
element is not permitted per the restrictions on SVG defined in [html].
MUST contain a valid document fragment that conforms to the XHTML content document model defined in 6.1.2 XHTML requirements.
If the [svg] title
element contains
marked-up text, the markup MUST contain only elements declared in the HTML namespace [infra].
Although the [svg] title
element allows markup elements, support for this
feature is limited. EPUB creators are advised to use text-only titles for maximum
interoperability.
This section defines requirements for technologies usable in both XHTML and SVG content documents.
This section is non-normative.
CSS is an integral part of the Open Web Platform. 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 maintains some prefixed properties to avoid breaking existing content. But with the minor exceptions defined in this section, EPUB defers to the W3C to define CSS.
Keep in mind that some reading systems will not support all desired features of CSS. The following are known to be particularly problematic:
Reading system-induced pagination can interact poorly with style sheets as reading systems sometimes paginate using columns. This may 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).
A CSS style sheet:
MAY include any CSS properties, with the following exceptions:
It MUST NOT include the direction
property [css-writing-modes-3].
It MUST NOT include the unicode-bidi
property [css-writing-modes-3].
MAY include the prefixed properties defined in 6.3.1.3 Prefixed properties.
MUST be encoded in UTF-8 or UTF-16 [unicode], with UTF-8 as the RECOMMENDED encoding.
This specification restricts the use of the direction
and
unicode-bidi
properties because reading systems might not
implement, or might switch off, CSS processing. EPUB creators must use the following
format-specific methods when they need control over these aspects of the rendering:
Earlier version of EPUB included prefixed CSS properties, as many CSS features related to world languages were not yet mature. To ensure backwards compatibility for content authored using these prefixes, they have been retained in this specification. Unless otherwise noted, prefixed properties and values behave exactly as their unprefixed equivalents as described in the appropriate CSS specification. The prefixed properties are documented in E. Prefixed CSS properties.
EPUB creators should use unprefixed properties and reading systems should support current CSS specifications. This specification retains the widely used prefixed properties from [epubcontentdocs-301] but removes support for the less-used ones. EPUB creators should use CSS-native solutions for the removed properties whenever available.
The Working Group recommends that EPUB creators currently using these prefixed properties move to unprefixed versions as soon as support allows, as the Working Group does not anticipate supporting them in the next major version of EPUB.
EPUB content documents MAY contain scripting using the facilities defined for this in the
respective underlying specifications ([html] and [svg]). When an EPUB content document
contains scripting, this specification refers to it as a scripted content document. This
label also applies to XHTML content documents that contain [html] form
elements.
The scripted
property of the manifest item
element is used to indicate that an EPUB content document is a
scripted content document.
When an [html] script
element contains a data
block [html], it does not represent scripted content.
[svg] does not define data blocks as of publication, but the same exclusion would apply if a future update adds the concept.
EPUB creators should note that reading systems are required to behave as though a unique origin [html] has been assigned to each EPUB publication. In practice, this means that it is not possible for scripts to share data between EPUB publications.
Which context a script is used in also determines the rights and restrictions that a reading system places on it (refer to Scripting [epub-rs-33] for more information).
Reading systems may 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).
EPUB 3 defines two contexts for script execution:
iframe
element; andScripts may execute in other contexts, but reading system support for these contexts
is optional. For example, a scripted SVG document may be referenced from an [html]
object
element.
Refer to the processing of scripts [epub-rs-33] for more information.
Whether EPUB creators embed the code directly in a script
element or
reference it via the element's src
attribute makes no difference to its
executing context.
Which context EPUB creators use for their scripts affects both what actions the scripts can perform and the likelihood of support in reading systems, as described in the following subsections.
Refer to H.2 Scripting contexts for an example of the difference between the two contexts.
A container-constrained script is either of the following:
An instance of the [html] script
element contained in an XHTML content document that is embedded in an XHTML content document using the [html]
iframe
element.
An instance of the [svg] script
element contained in an SVG content document that is embedded in a XHTML content document using the [html]
iframe
element.
A container-constrained script MUST NOT contain
instructions for modifying the DOM of the EPUB content document that embeds it
(i.e., the one that contains the iframe
element). It also MUST NOT contain
instructions for manipulating the size of its containing rectangle.
EPUB creators should note that support for container-constrained scripting in reading systems is only recommended in reflowable documents [epub-rs-33]. Furthermore, reading system support in fixed-layout documents is optional.
EPUB creators should ensure container-constrained scripts degrade gracefully in reading systems without scripting support (see 6.3.2.5 Scripting fallbacks).
EPUB creators choosing to restrict the usage of scripting to the container-constrained model will ensure a more consistent user experience between scripted and non-scripted content (e.g., consistent pagination behavior).
A spine-level script is an instance of the [html] script
or [svg] script
element contained in a top-level content document.
EPUB creators should note that support for spine-level scripting in reading systems is only recommended in fixed-layout documents and reflowable documents set to scroll [epub-rs-33]. Furthermore, reading system support in all other contexts is optional.
Top-level content documents that include spine-level scripting SHOULD remain consumable by the user without any information loss or other significant deterioration when scripting is disabled or not available (e.g., by employing progressive enhancement techniques or fallbacks). Failing to account for non-scripted environments in top-level content documents can result in EPUB publications being unreadable.
This section is non-normative.
EPUB creators should consider 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, EPUB creators should not rely on keyboard events alone; they should always provide alternative ways to trigger a desired action.
EPUB content documents that contain scripting SHOULD employ relevant [wai-aria] accessibility techniques to ensure that the content remains consumable by all users.
EPUB content documents that contain scripting MAY
provide fallbacks for such content, either by using intrinsic fallback mechanisms (such as
those available for the [html] object
and canvas
elements) or, when an intrinsic
fallback is not applicable, by using a manifest-level
fallback.
EPUB creators MUST ensure that scripts only generate core media type resources or fragments thereof.
This section is non-normative.
Not all rendering information can be expressed through the underlying technologies that EPUB is built upon. For example, although HTML with CSS provides powerful layout capabilities, those capabilities are limited to the scope of the document being rendered.
This section defines properties that allow EPUB creators to express package-level rendering intentions (i.e., functionality that can only be implemented by the EPUB reading system). If a reading system supports the desired rendering, these properties enable the user to be presented the content as the EPUB creator optimally designed it.
This section is non-normative.
EPUB publications, unlike print books or PDF files, are designed to change. The content flows, or reflows, to fit the screen and to fit the needs of the user. As noted in Rendering and CSS "content presentation adapts to the user, rather than the user having to adapt to a particular presentation of content." [epub-overview-33]
But this principle does not work for all types of documents. Sometimes content and design are so intertwined it is not possible to separate them. Any change in appearance risks changing the meaning or losing all meaning. Fixed-layout documents give EPUB creators greater control over presentation when a reflowable EPUB is not suitable for the content.
EPUB creators define fixed layouts using a set of package document properties to control the rendering in reading systems. In addition, they set the dimensions of each fixed-layout document in its respective EPUB content document.
EPUB 3 affords multiple mechanisms for representing fixed-layout content. When fixed-layout content is necessary, the EPUB creator's choice of mechanism will depend on many factors including desired degree of precision, file size, accessibility, etc. This section does not attempt to dictate the EPUB creator's choice of mechanism.
The rendition:layout
property specifies whether the content is reflowable or
pre-paginated.
When the rendition:layout
property is specified on a meta
element, it indicates that the
paginated or reflowable layout style applies globally (i.e., for all spine items).
EPUB creators MUST use one of the following values with the rendition:layout
property:
The content is not pre-paginated (i.e., reading systems apply dynamic pagination when rendering). Default value.
The content is pre-paginated (i.e., reading systems produce exactly one page per
spine
when rendering).itemref
Reading systems typically restrict or deny the application of user or user agent style sheets to pre-paginated documents because dynamic style changes are likely to have unintended consequence on the intrinsic properties of such documents. EPUB creators should consider the negative impact on usability and accessibility that these restrictions have when choosing to use pre-paginated instead of reflowable content. Refer to Guideline 1.4 - Provide text configuration [uaag20] for related information.
When the property is set
to pre-paginated
for a spine item, its content dimensions MUST be set as
defined in 8.2.2.6 Content document dimensions.
EPUB creators MUST NOT declare the rendition:layout
property more than once.
They also MUST NOT declare the property using the refines
attribute. Refer to 8.2.2.1.1 Layout overrides for
setting the property for individual EPUB content documents.
EPUB creators MAY specify the following properties locally
on spine
elements to override the global value for the given spine item:itemref
EPUB creators MUST NOT use more than one of these overrides on any given spine item.
The rendition:orientation
property specifies which orientation the EPUB creator intends the content to be rendered in.
When the rendition:orientation
property is specified on a
element,
it indicates that the intended orientation applies globally (i.e., for all spine items).meta
EPUB creators MUST use one of the following values with the
rendition:orientation
property:
Reading systems should render the content in landscape orientation.
Reading systems should render the content in portrait orientation.
The content is not orientation constrained. Default value.
EPUB creators MUST NOT declare the
rendition:orientation
property more than once.
They also MUST NOT declare the property using the refines
attribute. Refer to 8.2.2.2.1 Orientation overrides
for setting the property for individual EPUB content documents.
EPUB creators MAY specify the following properties
locally on spine
elements to override the global value for the given spine item:itemref
EPUB creators MUST NOT use more than one of these overrides on any given spine item.
The rendition:spread
property specifies the intended reading system
synthetic spread behavior.
When the rendition:spread
property is specified on a
meta
element, it indicates that the intended synthetic spread behavior
applies globally (i.e., for all spine items).
EPUB creators MUST use one of the following values with the rendition:spread
property:
Do not incorporate spine items in a synthetic spread. Reading systems should display the items in a single viewport positioned at the center of the screen.
Render a synthetic spread for spine items only when the device is in landscape orientation.
The use of spreads only in portrait orientation is deprecated.
EPUB creators should use the value "both
" instead, as spreads that are
readable in portrait orientation are also readable in landscape.
Render a synthetic spread regardless of device orientation.
The EPUB creator is not defining an explicit synthetic spread behavior. Default value.
EPUB creators MUST NOT declare the rendition:spread
property more than once.
They also MUST NOT declare the property using the refines
attribute. Refer to 8.2.2.3.1 Synthetic spread overrides for
setting the property for individual EPUB content documents.
When synthetic spreads are used in the context of XHTML and
SVG content documents, the dimensions given via the viewport meta
element and viewBox
attribute represents the size of one page in the
spread, respectively.
Refer to the
element for information about declaration of global flow
directionality using the spine
page-progression-direction
attribute and that of
local page-progression-direction within content documents.
EPUB creators MAY specify the following properties locally
on spine
elements to override the global value for the given spine item:itemref
The rendition:spread-portrait
property is deprecated.
spread-portrait
property definition
in [epubpublications-301] for more information.EPUB creators MUST NOT use more than one of these overrides on any given spine item.
When a reading system renders a synthetic spread, the default behavior is to populate
the spread by rendering the next EPUB content document in the next available unpopulated
viewport, where the next available viewport is determined by the given page progression direction or by
local declarations within EPUB content documents. An EPUB creator MAY override this
automatic population behavior and force reading systems to place a document in a particular
viewport by specifying one of the following properties on its spine itemref
element:
rendition:page-spread-center
rendition:page-spread-center
property is an alias of the spread-none
property for centering a spine
item.rendition:page-spread-left
rendition:page-spread-left
property is an alias of the page-spread-left
property for placing a
spine item in the left-hand slot of a two-page spread.rendition:page-spread-right
rendition:page-spread-right
property is an alias of the page-spread-right
property for placing a
spine item in the right-hand slot of a two-page spread.The rendition:page-spread-center
, rendition:page-spread-left
, and
rendition:page-spread-right
properties apply to both pre-paginated and
reflowable content. They only apply when the reading system is creating synthetic
spreads.
Although EPUB creators often indicate to use a spread in certain device orientations, the
content itself does not represent true spreads (i.e., two consecutive pages that reading
systems must render side-by-side for readability, such as a two-page map). To indicate that
two consecutive pages represent a true spread, EPUB creators SHOULD use the
rendition:page-spread-left
and rendition:page-spread-right
properties on the spine items for the two adjacent EPUB content documents,
and omit the properties on spine items where one-up or two-up presentation is equally
acceptable.
EPUB creators MUST NOT declare more than one rendition:page-spread-*
property,
and/or their unprefixed equivalents, on any given spine item (e.g., it is valid to specify
both "rendition:page-spread-left page-spread-left
" in case reading systems only
support one of properties).
The rendition:page-spread-left
and rendition:page-spread-right
properties were created to allow the use of a single vocabulary for all fixed-layout
properties. EPUB creators can use either property set, but older reading systems might
only recognize the unprefixed versions.
The rendition:page-spread-center
was created to make it easier for EPUB
creators to understand the process of switching between two-page spreads and single
centered pages. EPUB creators can use either rendition:page-spread-center
or spread-none
to disable spread behavior in reading systems.
The rendition:viewport
property allows EPUB creators to express the CSS
initial containing block (ICB) [css2] for XHTML and SVG content documents whose rendition:layout
property has been set to
pre-paginated
.
Use of the property is deprecated.
Refer to the rendition:viewport
property definition
in [epubpublications-301] for more information.
This section defines rules for the expression and interpretation of dimensional properties of fixed-layout documents.
Fixed-layout documents specify their initial containing block [css2] in the manner applicable to their format:
For XHTML fixed-layout documents, the initial
containing block [css2] is obtained from the REQUIRED height
and width
definitions in a viewport
meta
tag, where:
height
property MUST have as its value a positive number or the keyword
device-height
; andwidth
property MUST have as its value a positive number or the
keyword device-width
.The device-width
and device-height
values refer to the 100%
of the width and height, respectively, of the reading system's viewport.
The height
and width
definitions MUST be specified in the
first viewport meta
tag in document order in the [html] head
element. Reading systems
will ignore subsequent viewport meta
tags.
EPUB creators MUST NOT specify more than one height
or
width
definition within a viewport meta
tag.
For SVG fixed-layout documents, the initial containing block [css2]
dimensions MUST be expressed using the viewBox
attribute [svg].
The initial containing block definition affects only the document where it is defined. The dimensions of the containing blocks in the other content documents within the same publication may be different.
Although control over the rendering of EPUB content documents to create fixed layouts is an obvious need not handled by other technologies, there are also considerations for reflowable content that are unique to EPUB publications (e.g., how to handle the flow of content in the viewport). This section defines properties that allow EPUB creators to control presentation aspects of reflowable content.
The rendition:flow
property specifies the EPUB creator preference for how
reading systems should handle content overflow.
When the rendition:flow
property is
specified on a meta
element, it indicates the EPUB creator's global preference for
overflow content handling (i.e., for all spine items). EPUB creators MAY
indicate a preference for dynamic pagination or scrolling. For scrolled content, it is also
possible to specify whether consecutive EPUB content documents are to be rendered as a
continuous scrolling view or whether each is to be rendered separately (i.e., with a dynamic
page break between each).
EPUB creators MUST use one of the following values with the rendition:flow
property:
Dynamically paginate all overflow content.
Render all EPUB content documents such that overflow content is scrollable, and the EPUB publication is presented as one continuous scroll from spine item to spine item (except where locally overridden).
Note that EPUB creators SHOULD NOT create publications in which different resources have different block flow directions, as continuous scrolled rendition in EPUB reading systems would be problematic.
Render all EPUB content documents such that overflow content is scrollable, and each spine item is presented as a separate scrollable document.
Render overflow content using the reading system default method or a user preference, whichever is applicable. Default value.
Note that when two reflowable EPUB content documents occur
sequentially in the spine, the default rendering for their [html] body
elements is consistent with the page-break-before
property [csssnapshot] having been set to
always
. In addition to using the rendition:flow
property, EPUB
creators MAY override this behavior through an appropriate style sheet declaration, if the
reading system supports such overrides.
EPUB creators MUST NOT declare the rendition:flow
property more than once.
They also MUST NOT declare the property using the refines
attribute. Refer to 8.3.1.1 Spine overrides for setting the property for
individual EPUB content documents.
rendition:flow
set to paginated
.Three column-like rectangles linked left-to-middle and middle-to-right with respective arrows, with a text flowing from one rectangle to the next one. The text is sectioned with headers figuring 'Chapter 1', '2', and '3'. The leftmost rectangle is enclosed in a schematic view of a tablet.
rendition:flow
set to paginated
.Three column-like rectangles linked left-to-middle and middle-to-right with respective arrows, with a text flowing from one rectangle to the next one. The text is sectioned with headers figuring 'Chapter 1', '2'. The section with 'Chapter 2' starts at the top of the rightmost rectangle, leaving an empty space at the bottom of the middle rectangle. The leftmost rectangle is enclosed in a schematic view of a tablet.
rendition:flow
set to scrolled-continuous
.A single, column-like strip (i.e., a rectangle without a bottom edge) with a text flowing down the strip. The text is sectioned with headers figuring 'Chapter 1', '2'. The top part of the strip is enclosed in a schematic view of a tablet.
rendition:flow
set to scrolled-doc
.Three column-like strips (i.e., a rectangles without bottom edges) linked left-to-middle and middle-to-right with respective arrows, each containing a text flowing down the strip. The text is sectioned with headers figuring 'Chapter 1', '2' and '3'. Each strip starts with a chapter header and flows down the strip. The top part of the leftmost strip is enclosed in a schematic view of a tablet.
EPUB creators MAY specify the following properties
locally on spine
elements to override the global value for the given spine item:itemref
EPUB creators MUST NOT use more than one of these overrides on any given spine item.
The rendition:align-x-center
property specifies that the given spine item should be centered horizontally in the viewport or spread.
The property MUST NOT be set globally for all EPUB content documents (i.e., in a
element without a meta
refines
attribute). It is only
available as a spine override for individual EPUB content documents via the
element's itemref
properties
attribute.
This property was developed primarily to handle "Naka-Tobira (中扉)" (sectional title pages), in the absence of reliable centering control within the content rendering. As support for paged media evolves in CSS, however, this property is expected to be deprecated. EPUB creators are encouraged to use CSS solutions when effective.
This section is non-normative.
Mainstream ebooks, educational tools and ebooks formatted for persons with print disabilities are some examples of works that contain synchronized audio narration. In EPUB 3, EPUB creators can create these types of books using media overlay documents to describe the timing for the pre-recorded audio narration and how it relates to the EPUB content document markup. The specification defines the file format for media overlays as a subset of [smil3], a W3C recommendation for representing synchronized multimedia information in XML.
The text and audio synchronization enabled by media overlays provides enhanced accessibility for any user who has difficulty following the text of a traditional book. Media overlays also provide a continuous listening experience for readers who are unable to read the text for any reason, something that traditional audio embedding techniques cannot offer. They are even useful for purposes not traditionally considered accessibility concerns (e.g., for language learning).
The media overlays feature is transparent to EPUB reading systems that do not support the feature. The inclusion of media overlays in an EPUB publication has no impact on the ability of media overlay-unaware reading systems to render the EPUB publication as though the media overlays are not present.
Media overlays in EPUB are not an equivalent to audiobooks, as audiobooks are primarily audio-based with text occasionally provided as an alternate format. The W3C [audiobooks] recommendation is for building audio publications.
Although future versions of this specification might incorporate support for video media (e.g., synchronized text/sign-language books), this version supports only synchronizing audio media with the EPUB content document.
MUST be valid to the media overlays schema as defined in G.3 Media overlays schema and conform to all content conformance constraints expressed in 9.2.2 Media overlay document definition.
MAY refer to more than one EPUB content document, but more than one media overlay document MUST NOT reference the same EPUB content document.
All elements [xml] defined in this section are in the https://www.w3.org/ns/SMIL
namespace [xml-names] unless otherwise specified.
The smil
element encapsulates all the information in an media overlay document.
smil
REQUIRED root element [xml] of the media overlay document.
version
[required]
Specifies the version number of the [smil3] specification to which the media overlay document adheres.
This attribute MUST have the value "3.0
".
id
[optional]
The ID [xml] of the element, which MUST be unique within the document scope.
epub:prefix
[optional]
Declares additional metadata vocabulary prefixes.
Refer to 9.3.3 Structural semantics in overlays for more information.
In this order:
The head
element is the container for metadata in the media overlay document.
head
The head
element is the OPTIONAL first child of the
element.smil
None
metadata
[0 or 1]
As this specification does not define any metadata properties that must occur in the media
overlay document, the head
element is OPTIONAL.
The metadata
element represents metadata for the media overlay document. The
metadata
element is an extension point that allows the inclusion of
metadata from any metainformation structuring language.
metadata
As a child of the
element.head
None
[0 or more]
elements from any namespace
This specification does not require any metadata properties in the media overlay document;
the metadata
element is provided for custom metadata requirements.
The body
element is the starting point for the presentation contained in the
media overlay document. It contains the main sequence of
and par
elements.seq
body
The body
element is a REQUIRED child of the
element. It follows
the smil
element, when that element is present.head
epub:type
[optional]
An expression of the structural semantics of the corresponding element in the EPUB content document.
The value is a white space separated list of property types. Refer to 9.3.3 Structural semantics in overlays for more information.
id
[optional]
The ID [xml] of the element, which MUST be unique within the document scope.
epub:textref
[optional]
Refers to the associated EPUB content document and, optionally, identifies a specific part of it.
The value MUST be a path-relative-scheme-less-URL string, optionally
followed by U+0023 (#)
and a URL-fragment string.
In any order:
MUST include at least one par
or seq
.
The seq
element is a sequential time container for media objects and/or child
time containers.
seq
One or more seq
elements MAY occur as children of the
element
and of the body
element.seq
epub:type
[optional]
An expression of the structural semantics of the corresponding element in the EPUB content document.
The value is a white space separated list of property types. Refer to 9.3.3 Structural semantics in overlays for more information.
id
[optional]
The ID [xml] of the element, which MUST be unique within the document scope.
epub:textref
[required]
Refers to the associated EPUB content document and, optionally, identifies a specific part of it.
The value MUST be a path-relative-scheme-less-URL string, optionally
followed by U+0023 (#)
and a URL-fragment string.
Refer to 9.3.2.1 Overlay structure for more information.
In any order:
MUST include at least one par
or seq
.
The par
element is a parallel time container for media objects.
par
One or more par
elements MAY occur as children of the
and
body
elements.seq
epub:type
[optional]
An expression of the structural semantics of the corresponding element in the EPUB content document.
The value is a white space separated list of property types. Refer to 9.3.3 Structural semantics in overlays for more information.
id
[optional]
The ID [xml] of the element, which MUST be unique within the document scope.
In any order:
The text
element references an element in an EPUB content document. A
text
element typically refers to a textual element but can also refer to
other EPUB content document media elements. In the absence of a sibling
element, textual content referred to by this element may be rendered via text-to-speech.audio
text
As a REQUIRED child of the
element.par
src
[required]
Refers to the associated EPUB content document and, optionally, identifies a specific part of it.
The value MUST be a path-relative-scheme-less-URL string, optionally
followed by U+0023 (#)
and a URL-fragment string.
id
[optional]
The ID [xml] of the element, which MUST be unique within the document scope.
Empty
This specification places no restriction on the src
attribute of a
text
element. EPUB creators should, however, refer to a content that
can be styled with CSS to make the association with style
information effective (i.e., palpable content for XHTML or paths, basic shapes, or text elements in SVG).
[epub-rs-33] no longer provides guidance for reading systems on the playback
of timed media (i.e., the automatic starting of the referenced media). Although the
src
attribute of a text
element may refer to embedded timed
media (e.g., via an [html] video
element), referencing such media may have
unpredictable results.
The audio
element represents a clip of audio media.
audio
An OPTIONAL child of the
element.par
id
[optional]
The ID [xml] of the element, which MUST be unique within the document scope.
src
[required]
The relative- or absolute-URL string [url] reference to an audio file. The audio file MUST be one of the audio formats listed in the core media type resources table.
clipBegin
[optional]
A clock value that specifies the offset into the physical media corresponding to the start point of an audio clip.
MUST be a [smil3] clock value.
See H.4 Clock values.
clipEnd
[optional]
A clock value that specifies the offset into the physical media corresponding to the end point of an audio clip.
MUST be a [smil3] clock value.
See H.4 Clock values.
The chronological offset of the terminating position MUST be after the
starting offset specified in the clipBegin
attribute.
Empty
This section is non-normative.
EPUB creators can represent a pre-recorded narration of a publication as a series of audio clips, each corresponding to part of an EPUB content document. A single audio clip, for example, typically represents a single phrase or paragraph, but infers no order relative to the other clips or to the text of a document. Media overlays solve this problem of synchronization by tying the structured audio narration to its corresponding text (or other media) in the EPUB content document using [smil3] markup. Media overlays are, in fact, a simplified subset of SMIL 3.0 that define the playback sequence of these clips.
The SMIL elements primarily used for structuring media overlays are
(used for the main
sequence), body
(sequence) and seq
(parallel). (Refer to 9.2.2 Media overlay document definition
for more information on these and other SMIL elements.)par
The par
element is the basic building block of a media overlay and corresponds to a
phrase in the EPUB content document. The element provides two key pieces of information for
synchronizing content: 1) the audio clip containing the narration for the phrase; and 2) a
pointer to the associated EPUB content document fragment. The par
element uses two
media element children to represent this information: an
element and a audio
element. Because text
par
elements' media object children are timed in parallel, reading
systems render the audio clip and EPUB content document fragment at the same time, resulting in
a synchronized presentation.
The text
element src
attribute references the associated phrase,
sentence, or other segment of the EPUB content document by its URL [url] reference. The
audio
element src
attribute similarly references the location of
the corresponding audio clip and adds the OPTIONAL clipBegin
and clipEnd
attributes to indicate a specific offset within the clip.
EPUB creators place par
elements together sequentially to form a series of phrases
or sentences. Not every element of the EPUB content document will have a corresponding
par
element in a media overlay document, only those relevant to the audio
narration.
EPUB creators can also add par
elements to seq
elements to define more
complex structures such as parts and chapters (see 9.3.2.1 Overlay structure).
In this section, the EPUB content document is assumed to be an XHTML content document. While EPUB creators may use media overlays with SVG content documents, playback behavior might not be consistent and therefore interoperability is not guaranteed.
EPUB creators should also be aware that reading system support for playback of both reflowable and fixed-layout EPUB content documents is not guaranteed. Differences in reading system pagination strategies mean that some reading systems will only support media overlays in one or the other layout format.
The
of a media overlay document consists of two elements: the body
element
and the par
element. The ordering of these elements represents how reading systems
render the content in the corresponding EPUB content documents during playback.seq
The par
element represents a segment of content, such as a word, phrase,
sentence, table cell, list item, image, or other identifiable piece of content in the
markup. Each element identifies both the content to display (in the
element) and
audio to synchronize (in the text
element) during playback.audio
The seq
element represents sequences — sets of seq
and/or
par
elements that together represent a logical component of the content.
EPUB creators can use it to represent nested containers such as sections, asides,
headers, tables, lists, and footnotes. It allows EPUB creators to retain the structure
inherent in these containers in the media overlay document.
The seq
element MUST contain an epub:textref
attribute. As seq
elements do not
provide synchronization instructions, this attribute allows a reading system to match
the fragment to a location in the text.
The reason for grouping structures like sections, figures, tables, and footnotes in a
seq
element is so that reading systems can identify their start and end
positions during playback. Reading systems can then offer playback options tailored to
the layout of the content, such as jumping past a long figure, turning off rendering of
page break announcements (see 9.4 Skippability and escapability), or customizing
the reading mode to suit structures such as tables.
Both the epub:textref
attribute and the
element's text
src
attribute may contain a URL-fragment string that references a specific part (e.g., an
element via its ID) of the associated EPUB content document.
For XHTML and SVG content documents, the URL-fragment string SHOULD be a reference to a specific element via its ID, or an SVG Fragment Identifier [svg], respectively.
EPUB creators MAY use other fragment identifier schemes, but reading systems may not support such identifiers.
This section is non-normative.
The granularity level of the media overlay depends on how EPUB creators mark up the
EPUB content document and the type of fragment identifier they use in the
elements' text
src
attributes and the
elements' seq
epub:textref
attrbutes. For example, when referencing [html] elements, if the finest level of markup is
at the paragraph level, then that is the finest possible level for media overlay
synchronization. Likewise, if sub-paragraph markup is available, such as [html] span
element representing phrases or sentences, then finer granularity is possible in the media
overlay. Finer granularity gives users more precise results for synchronized playback when
navigating by word or phrase and when searching the text but increases the file size of the
media overlay documents. Fragment identifier schemes that do not rely on the presence of
elements could provide even finer granularity, where supported.
This specification allows the use of text-to-speech (TTS) — the rendering of the textual content of an EPUB publication as artificial human speech using a synthesized voice — in addition to pre-recorded audio clips.
When a media overlay
element omits its par
element, its audio
element may be
rendered in reading systems via TTS. If the text fragment is not appropriate for TTS
rendering (e.g., is not a text element and/or has no text fallback), this may produce
unexpected results.text
See EPUB 3 Text-to-Speech Support [epub-tts-10] for more information about using TTS technologies in EPUB publications.
To express structural semantics in media overlay documents, EPUB creators MAY specify the
attribute on epub:type
, par
, and
seq
elements.body
The epub:type
attribute facilitates reading system behavior appropriate for the
semantic type(s) indicated. Examples of these behaviors are skippability and escapability and table reading mode [epub-rs-33].
Media overlay documents MAY use the applicable vocabulary
association mechanisms for the epub:type
attribute to define additional
semantics.
EPUB creators MAY express visual rendering information for the currently playing EPUB content document element in a CSS Style Sheet using author-defined classes.
When used, EPUB creators MUST declare the class names in the package document using the active-class
and playback-active-class
properties.
EPUB creators MUST define exactly one CSS class name in each property they define. Each property MUST define a valid CSS class name not including any selectors [css2]. This specification does not reserve names for use with these properties.
EPUB creators MAY define any CSS properties for the specified CSS classes but must ensure that each EPUB content document with an associated media overlay document includes a CSS stylesheet (either embedded or linked) containing the class definitions. In the absence of such definitions reading systems might provide their own styling, or no styling at all.
EPUB creators MUST NOT use the active-class
and playback-active-class
properties in conjunction with a refines
attribute
as they always apply to the entire EPUB publication.
If an EPUB content document is wholly or partially referenced by a media overlay document, then its manifest
element MUST specify a
item
media-overlay
attribute. The attribute MUST reference the ID [xml] of the manifest item
for the
corresponding media overlay document.
EPUB creators MUST only specify the media-overlay
attribute on manifest
item
elements that reference EPUB content documents.
Manifest items for media overlay documents MUST have the media type
application/smil+xml
.
EPUB creators MUST specify the duration of the entire EPUB publication in the package document using a
element with the meta
duration
property.
In addition, EPUB creators MUST provide the duration of each media overlay document. EPUB
creators MUST use the refines
attribute to
associate each duration declaration to the corresponding manifest
.item
The sum of the durations for each media overlay document SHOULD equal the total duration plus or minus one second.
Although the sum of indivudal durations may not exactly match the total due to rounding the times to nearest fraction of a second, a difference of greater than one second indicates a mismatch arising from other issues.
EPUB creators MAY also specify narrator
information
in the package document, as well as author-defined CSS class
names to apply to the currently playing EPUB content document element.
The media:
prefix is reserved
for inclusion of these properties in package metadata.
While reading, users may want to turn on or off certain features of the content, such as
footnotes, page numbers, or other types of secondary content. This feature is called
skippability. Reading systems use the semantic information provided by media overlay
elements' epub:type
attribute to
determine when to offer users the option of skippable features.
EPUB creators MAY use the following semantics to enable skippability:
This list is non-exhaustive, however. It represents terms from the Structural Semantics Vocabulary [epub-ssv-11] for which reading systems are most likely to offer the option of skippability.
Escapable items are nested structures, such as tables and lists, that users might wish to skip over, continuing to read from the point immediately after the nested structure. The escapability feature differs from the skippability feature in that it does not enable or disable entire types of items, but provides an exit from them (e.g., a user can listen to some of the content before choosing to escape).
EPUB creators MAY use the following semantics to enable escapability:
This list is non-exhaustive list, however. It represents terms from the Structural Semantics Vocabulary [epub-ssv-11] for which reading systems are most likely to offer the option of escapability.
Sometimes escapable structures may contain escapable structures. For example, tables are composed of many rows and cells that users may want to separately escape from. Reading system support for escaping from such structures is complex and not well supported at this time. EPUB creators should avoid identifying nested escapable structures until better support is available.
This section is non-normative.
EPUB 3 builds upon the Open Web Platform expressly so that it can leverage the structure, semantics and, by extension, accessibility built into its underlying technologies.
The requirements and practices for creating accessible web content have already been documented in the W3C's Web Content Accessibility Guidelines (WCAG) [wcag2]. These guidelines also form the basis for defining accessibility in EPUB publications.
As the current WCAG guidelines (version 2) are heavily focused on web pages, a separate specification, EPUB Accessibility [epub-a11y-11], defines how to apply the standard to EPUB publications. It also adds EPUB-specific requirements and recommendations for metadata, pagination, and media overlays.
This specification recommends that EPUB publications conform to the accessibility requirements defined in [epub-a11y-11]. A benefit of following this recommendation is that it helps to ensure that EPUB publications meet the accessibility requirements legislated in jurisdictions around the world.
EPUB creators, however, should look beyond legal imperatives and treat accessibility as a requirement for all their content. The more accessible that EPUB publications are, the greater the potential audience for them.
This specification does not integrate the accessibility requirements to allow them to adapt and evolve independent of the EPUB specification — accessibility practices often need more frequent updating. The accessibility specification is also intended for use with past, present, and future versions of EPUB. The approach of a separate specification ensures that the evolution of EPUB does not lock accessibility in time (i.e., it allows producers of older versions of EPUB to reference the latest accessibility requirements).
This section is non-normative.
The particularity of an EPUB publication is its structure. The EPUB format provides a means of representing, packaging, and encoding structured and semantically enhanced web content — including HTML, CSS, SVG, JavaScript, and other resources — for distribution in a single-file container.
This means that EPUB 3's security and privacy issues are primarily linked to the features of those formats, and closely mirror the threats presented by web content.
Although content risks are often equated with deliberately malicious authoring intent, EPUB creators need to be aware that many practices followed with the best of intentions may expose users to privacy and security issues. The rest of this section explores the risk model of EPUB 3 with the aim of helping EPUB creators recognize and mitigate these risks.
For the risks associated with reading systems, refer to the security and privacy section of [epub-rs-33].
This section is non-normative.
EPUB publications pose a variety of privacy and security threats to unsuspecting users. Many of these threats intersect with web content, but EPUB also introduces its own unique methods of attack that can be used to trick users into accessing malicious content or into providing sensitive information. Some of the more important attack vectors that EPUB creators and users need to be aware of include:
EPUB 3 allows some publication resources to be remotely hosted, specifically resources whose sizes can negatively affect the downloading and opening of the EPUB publication (e.g., audio, video, and fonts). Although helpful for users when used as intended, these exemptions can also be used to inject malicious content into a publication.
This threat is not limited to accessing content created by a bad actor. If EPUB creators embed content from untrustworthy sources (e.g., third party audio and video), there is always the possibility that users may receive compromised resources.
Checking for malware and exploits at distribution time is not always reliable, either, as the malicious content can be swapped in any time after publication, unlike resources that come embedded in the EPUB container.
The origin of an EPUB is both unknown to the EPUB creator
and specific to each reading system implementation. Consequently, if the EPUB creator hosts
remote resources on a web server they control, the server effectively cannot use
security features that require specifying allowable origins, such as headers for CORS, Content-Security-Policy
, or X-Frame-Options
.
Whether intentional or not, links to external web sites and resources expose users to potential exploits that can compromise their reading system or operating system. Although external links will typically open in a web browser, and be subject to the browser security model, this does not protect users from all exploits.
Even if the intentions of the EPUB creator are not malicious, adding tracking information to external links is problematic for user privacy as it can allow a user's activity to be tracked without their consent.
Broken-link hijacking — when a domain expires and is bought by another party to exploit the links to it — can also lead to users being taken to resources the EPUB creator did not intend.
Resources embedded in the EPUB container are not immune to malicious actors, especially when EPUB publications are obtained from untrusted sources. Resources may contain exploits or forms that may submit sensitive information to unintended parties. Such actors may also try to gain access to remote resources using file indirection techniques, such as symbolic links or file aliases.
The use of third-party content, such as games and quizzes, may also lead to security and privacy issues if the EPUB creator is not able to fully vet the content.
When scripts can access a device's network, it provides a variety channels to exploit the user:
Network access may allow third-party content to exploit the user even if it was not the EPUB creator's intent.
The encryption and decryption of EPUB publications using digital rights management schemes may allow personally identifiable information about the user, what vendors they use, and their reading choices to be relayed to third parties.
The effectiveness of these attacks also often depends on tricking users into believing that the publication they are interacting with is from a trustworthy source. These deceptions can take the following forms:
The EPUB publication may include false information about itself to trick users into believing that it comes from a legitimate source. A malicious EPUB creator might, for example, fake the title, authors, identifiers, and publisher for the work.
Although this misinformation itself does not present an immediate harm, it could lead users to trust malicious forms, links, and other content within the EPUB publication believing it comes from a reliable source.
Malicious EPUB creators may also design their content to imitate or replicate a platform's experience to trick users into trusting their content.
EPUB 3 tries to avoid extending the underlying technologies it builds on, but it has introduced some new features. The restricted scope of these features limits the threats they might pose, however:
Content switching and multimedia control elements only allow hiding of content and script-less control of playback in HTML. Moreover, these features, introduced in the first release of EPUB 3.0, are deprecated and no longer recommended for use.
The expression of structural semantics in HTML and SVG only allows the annotation of elements.
The one potential exception is the epubReadingSystem
object [epub-rs-33] that allows EPUB creators
to query information about the current reading system. EPUB creators need to be mindful that
they only use the information exposed by this object to improve the rendering of their content
(i.e., avoid using the information to profile the user and their environment).
Although EPUB creators cannot prevent every method of exploiting users, they are ultimately responsible for the secure construction of their content. That means that they need to take precautions to limit the exposure of their EPUB publications to the types of malicious exploits described in the previous section.
Some practical steps include:
EPUB creators also need to consider the privacy rights of users and avoid situations where they are intentionally collecting data. Ideally, EPUB creators SHOULD NOT track their users, but this is not realistic for all types of publishing.
When EPUB creators have to track users, they SHOULD obtain the approval of the user to collect information prior to opening the EPUB publication (e.g., in educational course work). If this is not possible, they SHOULD obtain permission when users access the EPUB publication for the first time. EPUB creators SHOULD also allow users to opt out of tracking, and provide users the ability to manage and delete any data that is collected about them.
EPUB creators also need to consider the inadvertent collection of information about users. Linking to content on a publisher's web site, or remotely hosting resources on their servers, can lead to profiling users, especially if unique tracking identifiers are added to the URLs.
When collecting and storing user information within an EPUB publication (e.g., through the use of cookies and web storage [html]), EPUB creators need to consider to potential for data theft by other EPUB publications on a reading system. Although [epub-rs-33] introduces a unique origin requirement for EPUB publications, which limits the potential for attacks, there is still a risk that reading systems will allow EPUB publications access to shared persistent storage (e.g., older reading systems that have not been updated and non-conforming newer reading systems). Consequently, EPUB creators SHOULD NOT store sensitive user data in persistent storage. If EPUB creators must store sensitive data, they SHOULD encrypt the data to prevent trivial access to it in the case of an exploit.
When publishers and vendors must use digital rights management schemes, they should prefer schemes that do not utilize or transmit information about the user or their content to external parties to perform encryption or decryption.
To maximally reduce security and privacy risks, EPUB creators SHOULD produce their EPUB publications with the goal of long-term preservation. EPUB publications created this way are normally self-contained, not dependent on network access, and not encrypted with digital rights management, removing many of the possible attack vectors. [iso22424] is an example of such a preservation format for EPUB publications. While it is understood that not all EPUB creators can achieve these levels of self-containment, following as many of these practices as possible will still benefit overall user privacy and security.
This specification contains certain features that are not yet fully supported in reading systems, that the Working Group no longer recommends for use, or that are only retained for interoperability with EPUB 2 reading systems. This section defines the meanings of the designations attached to these features and their support expectations.
A under-implemented feature is a feature introduced prior to EPUB 3.3 for which the Working Group has not been able to establish enough implementation experience.
These features are considered important to retain despite this limitation because they are known to be implemented by EPUB creators (i.e., their deprecation would invalidate existing content) and/or they are integral to the content model on which EPUB is built.
If this specification designates a feature as under-implemented, EPUB creators MAY use the features as described.
EPUB conformance checkers should alert EPUB creators to the presence of under-implemented features when encountered in EPUB publications but must not treat their inclusion as a violation of the standard (i.e., not emit errors or warnings).
Whether under-implemented labels are removed or replaced by deprecation in a future version of the standard cannot be determined at this time. EPUB creators should strongly consider the interoperability problems that may arise both now and in the future when using these features.
The marking of features as under-implemented is a one-time event to account for the different process under which EPUB was developed prior to being brought into W3C. This label will not be used for new features developed under W3C processes.
A deprecated feature is one the Working Group no longer recommends for use in this version of the specification. Deprecated features typically have limited or no support in reading systems and/or usage in EPUB publications.
If this specification designates a feature as deprecated, EPUB creators SHOULD NOT use the feature in their EPUB publications.
EPUB conformance checkers should alert EPUB creators to the presence of deprecated features when encountered in EPUB publications.
The following table lists the public and system identifiers [xml] allowed in document type declarations. [xml]
EPUB creators MAY use these external identifiers only in publication resources with the listed media types [rfc2046] specified in their manifest declarations. (Refer to 3.9 XML conformance for more information.)
Media Type(s) | Public Identifier | System Identifier |
---|---|---|
|
-//W3C//DTD MathML 3.0//EN
|
http://www.w3.org/Math/DTD/mathml3/mathml3.dtd
|
application/x-dtbncx+xml
|
-//NISO//DTD ncx 2005-1//EN
|
http://www.daisy.org/z3986/2005/ncx-2005-1.dtd
|
image/svg+xml
|
-//W3C//DTD SVG 1.1//EN
|
http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd
|
This section is non-normative.
Structural semantics add additional meaning about the specific structural purpose an element plays.
The
attribute is used to express domain-specific semantics in EPUB content documents and media overlay documents, with the structural information it carries
complementing the underlying vocabulary.epub:type
The applied semantics refine the meaning of their containing elements without changing their nature
for assistive technologies, as happens when using the similar role
attribute [html]. The
attribute does not enhance the accessibility of the content, in other words; it only provides hints
about the purpose.
Semantic metadata enriches content for use in publishing workflows and for author-defined purposes. It also allows reading systems to learn more about the structure and content of a document (e.g., to enable skippability and escapability in media overlays).
This specification defines a method for adding structural semantics using the attribute
axis: instead of adding new elements, EPUB creators can append the epub:type
attribute to existing elements to add the desired semantics.
epub:type
http://www.idpf.org/2007/ops
Refer to the requirements for XHTML, SVG, and media overlays.
A white space-separated list of property values, with restrictions as defined in D.1 Vocabulary association mechanisms.
White space is the set of characters as defined in [xml].
Although the epub:type
attribute is similar in nature to the role
attribute [html], the attributes serve different purposes. The values of the
epub:type
attribute do not enhance access through assistive technologies like
screen readers as they do not map to the accessibility APIs used by these technologies. This
means that adding epub:type
values to semantically neutral elements like [html]
div
and span
does not make them any more accessible to assistive technologies. Only ARIA
roles influence how assistive technologies understand such elements.
The epub:type
attribute is consequently only intended for publishing semantics and
reading system enhancements. Reading systems may use epub:type
values to
provide accessibility enhancements like built-in read aloud or media overlays functionality
where interaction with assistive technologies is not essential.
Refer to Digital Publishing WAI-ARIA Module [dpub-aria] for more information about accessible publishing roles.
The epub: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.
The default vocabulary for the epub:type
attribute is
the EPUB 3 Structural Semantics Vocabulary [epub-ssv-11]. EPUB creators MAY include
unprefixed terms that are not part of this vocabulary, but the preferred method for adding custom
semantics is to use prefixes for them. Refer to D.1 Vocabulary association mechanisms for more information.
This appendix defines a general set of mechanisms by which attributes in this specification can reference terms from vocabularies. It also defines EPUB-specific vocabularies for use with the attributes.
This section is non-normative.
EPUB defines a formal method of referencing terms and properties defined in metadata and semantic
vocabularies using the property data type. The
epub:type
attribute uses this data type in EPUB content documents and
media overlay documents to add structural semantics,
for example, while the property
and rel
attributes use the data type
to define properties and relationships in the package document.
A property value is like a CURIE [rdfa-core] — it represents a URL [url] in compact form. The expression consists of a prefix and a reference, where the prefix — whether literal or implied — is a shorthand mapping of a URL that typically resolves to a term vocabulary. When a reading system converts the prefix to its URL representation and combines with the reference, the resulting URL normally resolves to a fragment within that vocabulary that contains human- and/or machine-readable information about the term.
To reduce the complexity for authoring, each attribute that takes a property data type also defines a default vocabulary. Terms and properties referenced from the default vocabularies do not include a prefix as the mapping reading systems use to map to a URL is predefined.
The power of the property data type lies in its easy extensibility. To incorporate new terms and properties, EPUB creators only need to declare a prefix. In another authoring convenience, this specification also reserves prefixes for many commonly used publishing vocabularies (i.e., their declaration is optional).
The following sections provide additional details on the property data type and vocabulary association mechanism.
The property data type is a compact means of expressing a URL [url] and consists of an OPTIONAL prefix separated from a reference by a colon.
property |
=
|
[ prefix , ":" ] , reference; | |
prefix |
=
|
? xsd:NCName ? ; | |
reference |
=
|
? path-relative-scheme-less-URL string [url] ? ; | /* as defined in [url] */ |
This specification derives the property data type from the CURIE data type defined in [rdfa-core]. A property represents a subset of CURIEs.
There are two key differences from CURIEs, however:
an empty reference does not represent a valid property value even though it is valid to the definition above (i.e., a property value that only consists of a prefix and colon is invalid).
an empty string does not represent a valid property even though it is valid to the definition above.
When an EPUB creator omits a prefix from a property value, the expressed reference represents a term from the default vocabulary for that attribute.
A default vocabulary is one that EPUB creators do not have to declare a prefix for in order to use its terms and properties where a property value is expected. EPUB creators MUST NOT add a prefix to terms and properties from a default vocabulary.
EPUB creators MUST NOT assign a prefix to the URLs associated with these vocabularies using the
prefix
attribute.
Refer to the definition of each attribute that takes a property data type for more information about its default vocabulary.
The prefix
attribute defines prefix mappings for use in property values.
The value of the prefix
attribute is a white space-separated list of one or more
prefix-to-URL mappings of the form:
prefixes |
=
|
mapping , { whitespace, { whitespace } , mapping } ; | |
mapping |
=
|
prefix , ":" , space , { space } , ? xsd:anyURI ? ; | |
prefix |
=
|
? xsd:NCName ? ; | |
space |
=
|
#x20 ; | |
whitespace |
=
|
(#x20 | #x9 | #xD | #xA) ; |
With the exception of reserved prefixes, EPUB creators
MUST declare all prefixes used in a document. EPUB creators MUST only specify the
prefix
attribute on the root element [xml] of
the respective format.
The attribute is not namespaced when used in the package document.
EPUB creators MUST declare the attribute in the namespace
http://www.idpf.org/2007/ops
in EPUB content documents and media overlay documents.
Although the prefix
attribute is modeled on the identically named
prefix
attribute in [rdfa-core], EPUB creators cannot use the attributes
interchangeably. The prefix
attribute without a namespace in EPUB content
documents is the RDFa attribute.
It is common for both attributes to appear in EPUB content documents that also specify RDFa expressions.
<html … prefix="…"
xmlns:epub="http://www.idpf.org/2007/ops"
epub:prefix="…"> …
</html>
Note that for embedded SVG, prefixes MUST be declared on the
[html] root html
element.
To avoid conflicts, EPUB creators MUST NOT use the prefix
attribute to declare a
prefix that maps to a default vocabulary.
EPUB creators MUST NOT declare the prefix '_' as this specification reserves this prefix for future compatibility with RDFa [rdfa-core] processing.
For future compatibility with alternative serializations of the package document, EPUB creators MUST NOT declare a prefix for the Dublin Core /elements/1.1/ namespace [dcterms]. EPUB creators MUST use only the [dcterms] elements allowed in the package document metadata.
Although reserved prefixes are an authoring convenience, EPUB creators should avoid relying on them as they may cause interoperability issues. EPUB conformance checkers will often reject new prefixes until their developers update the tools to the latest version of the specification, for example. EPUB creators should declare all prefixes they use to avoid such issues.
EPUB creators MAY use reserved prefixes in attributes that expect a property value without declaring them in a prefix
attribute.
EPUB creators SHOULD NOT override reserved prefixes in the prefix
attribute.
The reserved prefixes an EPUB creators can use depends on the context:
EPUB creators MAY use the following prefixes in package document attributes without having to declare them.
Prefix | URL |
---|---|
a11y | http://www.idpf.org/epub/vocab/package/a11y/# |
dcterms | http://purl.org/dc/terms/ |
marc | http://id.loc.gov/vocabulary/ |
media | http://www.idpf.org/epub/vocab/overlays/# |
onix | http://www.editeur.org/ONIX/book/codelists/current.html# |
rendition | http://www.idpf.org/vocab/rendition/# |
schema | http://schema.org/ |
xsd | http://www.w3.org/2001/XMLSchema# |
EPUB creators MAY use the following reserved prefixes in the epub:type
attribute without having
to declare them.
Prefix | URL |
---|---|
msv | http://www.idpf.org/epub/vocab/structure/magazine/# |
prism | http://www.prismstandard.org/specifications/3.0/PRISM_CV_Spec_3.0.htm# |
The fields in the vocabulary definition tables have the following implicit requirements:
Specifies the REQUIRED type of value using [xmlschema-2] datatypes.
Specifies which publication resource type(s) EPUB creators MAY specify the property on.
This field appears for properties used in the properties
attribute.
Specifies the number of times EPUB creators MAY specify the property, whether globally or attached to another element or property.
Properties with a minimum cardinality of one MUST be specified.
Describes the purpose of the property and specifies any additional usage requirements that EPUB creators must follow.
Provides non-normative usage examples.
Identifies what EPUB creators MAY associate the property with.
This field appears for properties that define primary expressions and subexpressions and relationships.
Specifies the name of the property as it MUST appear in the metadata.
The properties in this vocabulary are usable in the
element's meta
property
attribute.
Unless indicated otherwise in its "Extends" field, the properties defined in this section are used to
define subexpressions: in other words, a
element
carrying a property defined in this section MUST have a meta
refines
attribute referencing a resource or expression being
augmented.
The prefix URL for referencing these properties is
http://idpf.org/epub/vocab/package/meta/#
.
Name: |
alternate-script
|
---|---|
Description: |
The This property is typically attached to |
Allowed value(s): |
xsd:string
|
Cardinality: |
zero or more
|
Extends: | All properties. |
Name: |
belongs-to-collection
|
---|---|
Description: |
The It is also possible to chain these properties using the To allow reading systems to organize collections and avoid naming collisions (e.g.,
unrelated collections might share a similar name, or different editions of a
collection could be released), EPUB creators SHOULD provide an identifier that uniquely
identifies the instance of the collection. The The collection MAY more precisely define its nature by attaching a The position of the EPUB publication within the collection MAY be provided by
attaching a |
Allowed value(s): |
xsd:string
|
Cardinality: |
zero or more
|
Extends: | Applies to the EPUB publication and can refine other instances of itself. |
Name: |
collection-type
|
---|---|
Description: |
The When the This specification also defines the following collection types when no scheme is specified:
Note Although reading systems are not required to support these values, specifying them provides the option to group related EPUB publications in more meaningful ways. |
Allowed value(s): |
xsd:string
|
Cardinality: |
zero or one
|
Extends: |
belongs-to-collection
|
Name: |
display-seq
|
---|---|
Description: |
The This property only applies where precedence rules have not already been defined (e.g., precedence is given to creators based on their appearance in document order). |
Allowed value(s): |
xsd:unsignedInt
|
Cardinality: |
zero or one
|
Extends: | All properties. |
Name: |
file-as
|
---|---|
Description: | The file-as property provides the normalized form of the associated
property for sorting. |
Allowed value(s): |
xsd:string
|
Cardinality: |
zero or one
|
Extends: | All properties. |
Name: |
group-position
|
---|---|
Description: |
The EPUB creators can attach the An EPUB publication can belong to more than one group. |
Allowed value(s): | A single xsd:unsignedInt or series of decimal-separated numbers (e.g.,
1 or 2.2.1 ). |
Cardinality: |
zero or one
|
Extends: | All properties. |
Name: |
identifier-type
|
---|---|
Description: |
The When the |
Allowed value(s): |
xsd:string
|
Cardinality: |
zero or one
|
Extends: |
, dc:source
|
Use of this property is deprecated.
Refer to the meta-auth
property definition in [epubpublications-30] for more
information.
Name: |
role
|
---|---|
Description: |
The When the When attaching multiple roles to an individual or organization, the importance of the
roles should match the document order of their containing |
Allowed value(s): |
xsd:string
|
Cardinality: |
zero or more
|
Extends: |
, , dc:publisher
|
Name: |
source-of
|
---|---|
Description: |
The This specification defines the |
Allowed value(s): |
pagination
|
Cardinality: |
zero or one
|
Extends: |
dc:source
|
See [epub-a11y-tech-11] for information on how to provide accessible page navigation.
Name: |
term
|
---|---|
Description: |
The |
Allowed value(s): |
xsd:string
|
Cardinality: |
zero or one
|
Extends: |
|
Name: |
title-type
|
---|---|
Description: |
The When the |
Allowed value(s): |
xsd:string
|
Cardinality: |
zero or one
|
Extends: |
|
The properties in this vocabulary are usable in the metadata
element's link
rel
and properties
attributes.
The prefix URL for referencing these properties is
http://idpf.org/epub/vocab/package/link/#
.
The following values can be used in the link
element rel
attribute to establish the relationship of the resource referenced in
the href
attribute.
Name: |
alternate
|
---|---|
Description: |
The
|
Cardinality: |
Zero or more
|
Extends: | Only applies to the EPUB publication or collection. MUST NOT be used when the refines attribute is present. |
Example: |
<link rel="alternate" href="package.json"
media-type="application/json-ld"/>
|
Use of the marc21xml-record
keyword is deprecated.
It is replaced by the record
keyword with the media-type
attribute value
"application/marcxml+xml
".
Refer to the marc21xml-record
property definition in [epubpublications-30] for more information.
Use of the mods-record
keyword is deprecated. It
is replaced by the record
keyword with the media-type
attribute value
"application/mods+xml
".
Refer to the mods-record
property definition in [epubpublications-30] for more information.
Use of the onix-record
keyword is deprecated. It
is replaced by the record
keyword with the properties attribute value onix
.
Refer to the onix-record
property definition in [epubpublications-30] for more information.
Name: |
record
|
---|---|
Description: |
Indicates that the referenced resource is a metadata record. The media type of the record MUST be identified in the For a list of commonly linked metadata record types, refer to the EPUB Linked Metadata Guide If the type of record cannot be identified from the media type, an identifier property can be assigned in the
|
Cardinality: |
Zero or more
|
Extends: | Only applies to the EPUB publication or collection. MUST NOT be used when the refines attribute is present. |
Example: |
<link rel="record" href="book/52.atom"
media-type="application/atom+xml;type=entry;profile=opds-catalog"/>
|
Name: |
voicing
|
---|---|
Description: |
Indicates that the referenced audio file provides an aural representation of the expression or resource (typically, the title or creator) specified by the refines attribute. The media type of the audio file MUST be identified in the |
Cardinality: |
Zero or more
|
Extends: | All properties. The refines attribute
MUST be present when this value is used. |
Example: |
<link refines="#title" rel="voicing" media-type="audio/mpeg"
href="title.mp3" />
|
Use of the xml-signature
keyword is deprecated.
It is not replaced by another linking method.
Refer to the xml-signature
property definition in [epubpublications-30] for more information.
Use of the xmp-record
keyword is deprecated.
Refer to the xmp-record
property definition in [epubpublications-30] for more information.
The following values can be used in the
element's
link
properties
attribute to establish the type of record a referenced resource represents.
These values are provided for record formats that cannot be uniquely identified by their media
type.
Name: |
onix
|
---|---|
Description: | The onix property indicates the referenced resource is an ONIX record
[onix]. |
Example: |
<link rel="record" href="pub/meta/nor-wood-onix.xml"
media-type="application/xml" properties="onix"/>
|
The prefix URL for referencing these properties is
http://www.idpf.org/vocab/rendition/#
.
The "rendition:
" prefix is reserved for
use with the package rendering properties and does not have to be declared in the
package document.
Unlike the other vocabularies in this appendix, the properties in the Package Rendering Vocabulary
consist of a mix of properties (expressed in
elements)
and spine overrides (expressed on meta
elements).itemref
The usage requirements are also defined in 8. Layout rendering control not in this appendix. The following table provides a map to the properties, overrides, and where they are defined.
Property | Overrides | Defined in |
---|---|---|
rendition:layout |
|
8.2.2.1 Layout |
rendition:orientation |
|
8.2.2.2 Orientation |
rendition:spread |
|
8.2.2.3 Synthetic spreads |
— |
|
8.2.2.4 Spread placement |
rendition:viewport (Deprecated) |
— | 8.2.2.5 Viewport dimensions (deprecated) |
rendition:flow |
|
8.3.1 The rendition:flow property |
— |
|
8.3.2 The rendition:align-x-center property |
Reading system developers may introduce functionality not defined in this specification to address reading system-specific issues rendering EPUB content documents.
To facilitate this experimentation, EPUB creators MAY include custom properties and spine
overrides for use in the package document provided they do not use the rendition:
prefix.
Custom properties should only address rendering issues specific to a particular reading system. This specification should be extended to provide extensions that multiple independent reading systems can use.
The properties in this vocabulary are usable in the manifest
element's item
properties
attribute.
The prefix URL for referencing these properties is
http://idpf.org/epub/vocab/package/item/#
.
Name: |
cover-image
|
---|---|
Description: | The cover-image property identifies the described publication resource as
the cover image for the EPUB publication. |
Applies to: | All raster and vector image types |
Cardinality: |
Zero or one
|
Name: |
mathml
|
---|---|
Description: | The mathml property indicates that the described publication resource
contains one or more instances of MathML markup. |
Applies to: | EPUB content documents |
Cardinality: |
Zero or more
|
Name: |
remote-resources
|
---|---|
Description: |
The Refer to 3.6 Resource locations for more information. |
Applies to: | All publication resources with the capability of internal referencing (e.g., XHTML content documents, SVG content documents, CSS style sheets and media overlay documents). |
Cardinality: |
Zero or more
|
Name: |
scripted
|
---|---|
Description: | The scripted property indicates that the described publication resource is
a scripted content document (i.e., contains scripting and/or [html] form
elements). |
Applies to: | EPUB content documents |
Cardinality: |
Zero or more
|
Name: |
svg
|
---|---|
Description: |
The This property MUST be set when SVG markup is included directly in the resource and
MAY be set when the SVG is referenced from the resource (e.g., from an [html]
|
Applies to: | XHTML content documents; the value is implied for SVG content documents. |
Cardinality: |
Zero or more
|
Name: |
switch
|
---|---|
Description: |
The |
Applies to: | XHTML content documents. |
Cardinality: |
Zero or more
|
The properties in this vocabulary are usable in the spine
element's
itemref
properties
attribute.
The prefix URL for referencing these properties is
http://idpf.org/epub/vocab/package/itemref/#
.
Name: |
page-spread-left
|
---|---|
Description: |
The The |
Name: |
page-spread-right
|
---|---|
Description: |
The The |
The properties in this vocabulary are usable in the
element's
meta
property
attribute.
The prefix URL for referencing these properties is
http://www.idpf.org/epub/vocab/overlays/#
.
The prefix "media:
" is reserved for use with
properties in this vocabulary and does not have to be declared in the package document.
Name: |
active-class
|
---|---|
Description: | EPUB creator-defined CSS class name to apply to the currently playing EPUB content document element. |
Allowed value(s): |
xsd:string
|
Cardinality: |
Zero or one
|
Example: |
<meta
property="media:active-class">-epub-media-overlay-active</meta>
|
Name: |
duration
|
---|---|
Description: | The duration of the entire presentation or of a specific media overlay document. The specified durations account for the audio clips known at authoring time, and so exclude live streaming from external resources and speech synthesis. |
Allowed value(s): |
MUST be a [smil3] clock value. |
Cardinality: | Exactly one for the EPUB publication and for each media overlay document. |
Example: |
<meta property="media:duration">1:36:20</meta>
|
Name: |
narrator
|
---|---|
Description: | Name of the narrator. |
Allowed value(s): |
xsd:string
|
Cardinality: |
Zero or more
|
Example: |
<meta property="media:narrator">Joe Speaker</meta>
|
Name: |
playback-active-class
|
---|---|
Description: | Author-defined CSS class name to apply to the EPUB content document's document element when playback is active. |
Allowed value(s): |
xsd:string
|
Cardinality: |
Zero or one
|
Example: |
<meta
property="media:playback-active-class">-epub-media-overlay-playing</meta>
|
This appendix describes the prefixed CSS properties supported by EPUB.
The prefix definitions are no longer being synchronized with their CSS counterparts. In some cases, the unprefixed versions of these properties now support additional values. Reading systems may not support the new syntax with the prefixed properties, so EPUB creators are advised to use the unprefixed versions for newer features.
This section describes the -epub-
prefixed properties for [css-writing-modes-3].
This property is a prefixed version of the text-orientation
property [css-writing-modes-3].
Name: | -epub-text-orientation |
---|---|
Value: | mixed | upright | sideways | sideways-right |
For compatibility with existing content, the -epub-text-orientation
property also
supports the deprecated vertical-right
, rotate-right
, and
rotate-normal
keywords. The following table specifies the effect these have
when specified.
Deprecated value | Value to be used |
---|---|
vertical-right |
mixed |
rotate-right |
sideways |
rotate-normal |
sideways |
This property is a prefixed version of the writing-mode
property
[css-writing-modes-3], with the same syntax and behavior.
Name: | -epub-writing-mode |
---|---|
Value: | horizontal-tb | vertical-rl | vertical-lr |
These properties are prefixed versions of the text-combine-upright
property [css-writing-modes-3], although -epub-text-combine
is
deprecated.
Name: | -epub-text-combine-horizontal |
---|---|
Value: | none | all |
Name: | -epub-text-combine (deprecated) |
---|---|
Value: | none | horizontal | horizontal <number> |
For compatibility with existing content, the -epub-text-combine-horizontal
and
-epub-text-combine
properties also support a number of deprecated keywords. The
following table specifies the effect these have when specified.
Prefixed version | CSS equivalent |
---|---|
-epub-text-combine-horizontal: none |
text-combine-upright: none |
-epub-text-combine-horizontal: all |
text-combine-upright: all |
-epub-text-combine: none |
text-combine-upright: none |
-epub-text-combine: horizontal |
text-combine-upright: all |
-epub-text-combine: horizontal <number> |
no equivalent |
This section describes the -epub-
prefixed properties (and one prefixed value) for
[css-text-3].
This property is a prefixed version of the hyphens
property [css-text-3].
Name: | -epub-hyphens |
---|---|
Value: | none | manual | auto | all |
For compatibility with existing content, the -epub-hyphens
property also supports
the deprecated all
keyword. The value is no longer supported in CSS and there is no
equivalent to use in its place.
This property is a prefixed version of the line-break
property [css-text-3].
Name: | -epub-line-break |
---|---|
Value: | auto | loose | normal | strict |
This property is a prefixed version of the text-align-last
property [css-text-3].
Name: | -epub-text-align-last |
---|---|
Value: | auto | start | end | left | right | center | justify |
This property is a prefixed version of the word-break
property [css-text-3].
Name: | -epub-word-break |
---|---|
Value: | normal | keep-all | break-all |
This property is a prefixed value for the text-transform
property [css-text-3].
Name: | text-transform |
---|---|
Value: | -epub-fullwidth |
For compatibility with existing content, the text-transform
property also supports
the deprecated -epub-fullwidth
keyword. When specified, this has the same effect as
text-transform: full-width
.
This section describes the -epub-
prefixed properties for [css-text-decor-3].
This property is a prefixed version of the text-emphasis-color
property [css-text-decor-3].
Name: | -epub-text-emphasis-color |
---|---|
Value: | <color> |
This property is a prefixed version of the text-emphasis-position
property [css-text-decor-3].
Name: | -epub-text-emphasis-position |
---|---|
Value: | [ over | under ] && [ right | left ] |
This property is a prefixed version of the text-emphasis-style
property [css-text-decor-3].
Name: | -epub-text-emphasis-style |
---|---|
Value: | none | [ [ filled | open ] || [ dot | circle | double-circle | triangle | sesame ] ] | <string> |
This property is a prefixed version of the text-underline-position
property [css-text-decor-3].
Name: | -epub-text-underline-position |
---|---|
Value: | auto | [ under || [ left | right ] ] | alphabetic |
For compatibility with existing content, the value -epub-text-underline-position
property also supports the deprecated alphabetic
keyword. When specified, this has
the same effect as text-underline-position: auto
.
This section is non-normative.
As the Safari HTML definition of the viewport meta
tag, that was used in earlier
versions of EPUB 3, is not an officially recognized standard, this specification defines a
basic syntax in order to allow EPUB creators to express width and
height dimensions for use rendering fixed-layout documents.
The syntax of this grammar is also influenced by the parsing algorithm for the viewport
meta
tag, as defined in [css-viewport-1].
The syntax is intentionally left as generic as possible as it is not in this specification's scope to define all the possible properties and values. It only defines the basic requirements for defining a property and value pair as well as the possible separators between expressions.
For fixed-layout documents, a viewport
meta
tag [html] MUST have name
and content
attributes that conform to the following definition:
name
attribute [html] after whitespace normalization [xml] MUST be viewport
.The value of the content
attribute [html] after whitespace normalization [xml] MUST be of the following form:
viewport | = | property, { sep, property } ; |
property | = | name, [ assign, value ] ; |
name | = | ? character data ? ; |
value | = | ? character data ? ; |
sep | = | sep-char, { sep-char } ; |
sep-char | = | ( ";" | "," | space ) ; |
assign | = | [ space ], "=", [ space ] ; |
space | = | #x20 ; |
The only restriction on property names and values is that they MUST NOT contain separator characters or the assignment character.
The authoring requirements in this section apply after whitespace normalization [xml] (i.e., after a reading system strips leading and trailing whitespace and compacts all instances of multiple whitespace within the attribute to single spaces). EPUB creators MAY include any valid ascii whitespace [infra] in the authored tag so long as the result is valid to this definition.
There are no restrictions on any other attributes allowed on the meta
element by the [html] grammar.
For more information about specifying the required height
and width
properties, and their required values, refer to 8.2.2.6 Content document dimensions.
Although the viewport meta
tag allows EPUB creators to use properties other than
height
and width
, and to not include values for these properties,
such use is strongly discouraged. Setting other properties may have unintended consequences on
the rendering of fixed-layout documents.
This section is non-normative.
A schema for package documents is available at https://github.com/w3c/epubcheck/tree/master/src/main/resources/com/adobe/epubcheck/schema/30/package-30.nvdl.
Validation using this schema requires a processor that supports [nvdl], [relaxng-schema], [isoschematron] and [xmlschema-2].
The NVDL schema layer can be substituted by a multi-pass validation using the embedded RELAX NG and ISO Schematron schemas alone.
These schemas may be updated and corrected outside of formal revisions of this specification. As a result, they are subject to change at any time.
A schema for container.xml
files
is available at
https://github.com/w3c/epubcheck/tree/master/src/main/resources/com/adobe/epubcheck/schema/30/ocf-container-30.nvdl
.
Validation using this schema requires a processor that supports [relaxng-schema] and [xmlschema-2].
The schema for encryption.xml
files is included in [xmlsec-rngschema-20130411].
The schema for signatures.xml
files is included in [xmlsec-rngschema-20130411].
A schema for media overlay documents is available at https://github.com/w3c/epubcheck/tree/main/src/master/resources/com/adobe/epubcheck/schema/30/media-overlay-30.nvdl.
Validation using this schema requires a processor that supports [nvdl], [relaxng-schema], [isoschematron] and [xmlschema-2].
The NVDL schema layer can be substituted by a multi-pass validation using the embedded RELAX NG and ISO Schematron schemas alone.
This section is non-normative.
Consider the following extracts of a package document and an XHTML content document:
<package …>
<metadata …>
…
<link rel="record"
href="meta/data.xml"
media-type="application/marc"/>
<link rel="record"
href="https://www.example.org/meta/data2.xml"
media-type="application/marc"/>
…
</metadata>
<manifest>
…
<item id="page"
href="page.xhtml"
media-type="application/xhtml+xml"/>
<item id="nav"
href="nav.xhtml"
media-type="application/xhtml+xml"
properties="nav"/>
<item id="style"
href="style.css"
media-type="text/css"/>
<item id="font_otf"
href="fonts/font-file.otf"
media-type="font/otf"/>
<item id="font_otf_remote"
href="https://www.example.org/fonts/font-file2.otf"
media-type="font/otf"/>
<item id="font_cff"
href="fonts/font-file.cff"
media-type="font/sfnt"/>
<item id="pls"
href="speech/cmn.pls"
media-type="application/pls+xml"/>
<item id="image_1"
href="media/image_1.png"
media-type="image/png"/>
<item id="image_2"
href="media/image_2.png"
media-type="image/png"
fallback="image_desc"/>
<item id="image_desc"
href="image_desc.xhtml"
media-type="application/xhtml+xml"/>
<item id="image_3_heic"
href="media/image_3.heic"
media-type="image/heic"/>
<item id="image_3_png"
href="media/image_3.png"
media-type="image/png"/>
<item id="widget"
href="widget.xhtml"
media-type="application/xhtml+xml"/>
…
</manifest>
<spine>
…
<itemref idref="page_001"/>
<itemref idref="image_2"/>
…
</spine>
</package>
<html …>
<head …>
…
<link rel="stylesheet" type="text/css" href="style.css"/>
<link rel="pronunciation" type="application/pls+xml" href="speech/cmn.pls"/>
…
</head>
<body>
<img src="media/image1_png"/>
…
<a href="media/image_2.png">…</a>
…
<picture>
<source srcset="media/image_3.heic" type="image/heic"/>
<img src="media/image_3.png"/>
</picture>
…
<iframe src="widget.xhtml"></iframe>
…
<a href="https://www.example.org/some_content">…</a>
</body>
</html>
The various resources in the EPUB publication can be categorized as follows. (Refer to 3. Publication resources for more information about these categories.)
meta/data.xml
The resource is a metadata record, stored in the EPUB container. It is linked via a
element in the package document metadata. It is therefore a linked resource on
the manifest plane (i.e., is not listed in the manifest). It is not
part on any other planes. link
https://www.example.org/meta/data2.xml
The resource is a metadata record, stored remotely. It is linked via a
element in
the package document metadata. It is therefore a linked resource on the manifest plane,
(i.e., it is not listed in the manifest). It is not part on any other planes.link
page.xhtml
The resource is an XHTML document. It is listed in the [[EPUB spine | spine=]. It is a publication resource on the manifest plane, a container resource, an EPUB content document on the spine plane, and is not present on the content plane. No fallback is necessary.
nav.xhtml
The resource is the EPUB navigation document. It is not listed in the spine. It is a publication resource on the manifest plane, a container resource, and is not present on either the spine plane or the content plane. No fallback is necessary.
style.css
The resource is a CSS file. It is not listed in the spine but is referenced from an [html]
link
element. It is a publication
resource on the manifest plane, a container resource, is not present on the spine plane, and
is a core media type resource on the content plane. No fallback is necessary.
font/font-file.otf
The resource is a TrueType font file. It is not listed in the spine but is referenced from a CSS file. It is a publication resource on the manifest plane, is a container resource, is not present on the spine plane, and is a core media type resource on the content plane. No fallback is necessary.
https://www.example.org/fonts/font-file2.otf
The resource is a TrueType font file. It is not listed in the spine but is referenced from a CSS file. It is a publication resource on the manifest plane, is a remote resource, is not present on the spine plane, and is a core media type resource on the content plane. No fallback is necessary.
font/font-file.cff
The resource is a font file in Compact Font Format. It is not listed in the spine but is referenced from a CSS file. Its media type is not listed as a core media type. It is a publication resource on the manifest plane, a container resource, is not present on the spine plane, and is an exempt resource on the content plane. No fallback is necessary.
speech/cmn.pls
The resource is a Pronunciation Lexicon file. It is not listed in the spine but is referenced
from an [html] link
element. It is a
publication resource on the manifest plane, a container resource, not present on the spine
plane, and is an exempt resource on the content plane. No fallback is necessary.
image/image_1.png
The resource is a PNG image file. It is not listed in the spine but is referenced from an
[html] img
element. It is a publication resource on the manifest plane, a container
resource, is not present on the spine plane, and is a core media type resource on the
content plane. No fallback is necessary.
image/image_2.png
The resource is a PNG image file. It is referenced via an [html] a
element. Because it
is referenced from a hyperlink, it must be listed in the spine. It is a publication
resource on the manifest plane, a container resource, a foreign content document on the
spine plane, and a core media type resource on the content plane. As a foreign content
document, a fallback is required, which is provided via a manifest fallback.
image_desc.xhtml
The resource is an XHTML document. It is the "target" of a manifest fallback so is not explicitly listed in the spine (but it "replaces" the existing spine item when needed). It is a publication resource on the manifest plane, a container resource, an EPUB content document on spine plane, and, because it is not "used" when rendering another EPUB content document, it is not present on the content plane. No fallback is necessary.
image/image_3.heic
The resource is a High Efficiency (HEIC) image file. It is not listed in the spine but is
referenced from an [html] source
element. Its media type is not listed as a core media type. It is a publication resource on the
manifest plane, a container resource, is not present on the spine plane, and is a foreign
resource on the content plane. As a foreign resource, a fallback is required, which is
provided via the sibling [html] img
element in an [html] picture
element.
image/image_3.png
The resource is a PNG image file. It is not listed in the spine but is referenced from an
[html] img
element that is used as an intrinsic fallback of the [html] picture
element. It is a publication resource on the manifest plane, a container resource, is not
present on the spine plane, and is a core media type resource on the content plane. No
fallback is necessary.
widget.xhtml
The resource is an XHTML document. It is not listed in the spine but is referenced from an
[html] iframe
element. It is a publication resource on the manifest plane, a container
resource, is not present on spine plane, and, because it is "used" when rendering another
EPUB content document, a core media type resource on the content plane. No fallback is
necessary.
https://www.example.org/some_content
The resource is referenced via an [html] a
element and is not stored in the EPUB
container. Reading systems will normally open this link via a separate browser instance. It
is not on any planes defined by this specification.
Additional examples on the usage of different types of resources can be found in 5.6.2.2 Examples.
Consider the following example package document:
<package …>
…
<manifest>
…
<item id="chap01"
href="scripted01.xhtml"
media-type="application/xhtml+xml"
properties="scripted"/>
<item id="inset01"
href="scripted02.xhtml"
media-type="application/xhtml+xml"
properties="scripted"/>
<item id="slideshowjs"
href="slideshow.js"
media-type="text/javascript"/>
</manifest>
<spine …>
<itemref idref="chap01"/>
…
</spine>
…
</package>
and the following file scripted01.xhtml
:
<html …>
<head>
…
<script type="text/javascript">
const te = navigator.epubReadingSystem.hasFeature("touch-events");
const te_message = te ? "passes" : "does not pass";
alert(`The reading system ${te_message} touch events to the content.`);
</script>
</head>
<body>
…
<iframe src="scripted02.xhtml" … />
…
</body>
</html>
and the following file scripted02.xhtml
:
<html …>
<head>
…
<script type="text/javascript" href="slideshow.js"></script>
</head>
<body>
…
</body>
</html>
From these examples, it is true that:
the code in the script
element in the head
in
scripted01.xhtml
is a spine-level script
because the document is referenced from the spine; and
the code in the script
element in scripted02.xhtml
is a container-constrained script because the
XHTML document it occurs in is included in scripted01.xhtml
via the
iframe
element.
This example demonstrates the use of the OCF format to contain a signed and encrypted EPUB publication within an OCF ZIP container.
Ordered list of files in the OCF ZIP container:
mimetype
META-INF/container.xml
META-INF/signatures.xml
META-INF/encryption.xml
EPUB/As_You_Like_It.opf
EPUB/book.html
EPUB/nav.html
EPUB/images/cover.png
The contents of the mimetype
file
application/epub+zip
The contents of the META-INF/container.xml
file
<?xml version="1.0"?>
<container
version="1.0"
xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
<rootfiles>
<rootfile
full-path="EPUB/As_You_Like_It.opf"
media-type="application/oebps-package+xml"/>
</rootfiles>
</container>
The contents of the META-INF/signatures.xml
file
<signatures
xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
<Signature
Id="AsYouLikeItSignature"
xmlns="http://www.w3.org/2000/09/xmldsig#">
<!--
SignedInfo is the information that is actually signed.
In this case, the SHA-1 algorithm is used to sign the
canonical form of the XML documents enumerated in the
Object element below.
-->
<SignedInfo>
<CanonicalizationMethod
Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
<SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/>
<Reference
URI="#AsYouLikeIt">
<DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>
…
</DigestValue>
</Reference>
</SignedInfo>
<!--
The signed value of the digest above, using the DSA
algorithm
-->
<SignatureValue>
…
</SignatureValue>
<!--
The key used to validate the signature
-->
<KeyInfo>
<KeyValue>
<DSAKeyValue>
<P>…</P>
<Q>…</Q>
<G>…</G>
<Y>…</Y>
</DSAKeyValue>
</KeyValue>
</KeyInfo>
<!--
The list of resources to sign (note that the canonical
form of XML documents is signed, while the binary form
of all other resources is used)
-->
<Object>
<Manifest
Id="AsYouLikeIt">
<Reference
URI="EPUB/As_You_Like_It.opf">
<Transforms>
<Transform
Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
</Transforms>
<DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>
</DigestValue>
</Reference>
<Reference URI="EPUB/book.html">
<Transforms>
<Transform
Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
</Transforms>
<DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>
</DigestValue>
</Reference>
<Reference
URI="EPUB/images/cover.png">
<DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>
</DigestValue>
</Reference>
</Manifest>
</Object>
</Signature>
</signatures>
The contents of the META-INF/encryption.xml
file
<?xml version="1.0"?>
<encryption
xmlns="urn:oasis:names:tc:opendocument:xmlns:container"
xmlns:enc="http://www.w3.org/2001/04/xmlenc#"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<!--
The RSA-encrypted AES-128 symmetric key used to encrypt
data enumerated in EncryptedData blocks below
-->
<enc:EncryptedKey
Id="EK">
<enc:EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
<ds:KeyInfo>
<ds:KeyName>
John Smith
</ds:KeyName>
</ds:KeyInfo>
<enc:CipherData>
<enc:CipherValue>
xyzabc…
</enc:CipherValue>
</enc:CipherData>
</enc:EncryptedKey>
<!--
Each EncryptedData block identifies a single resource
that has been encrypted using the AES-128 algorithm.
The data remains stored, in its encrypted form, in the
original file within the container.
-->
<enc:EncryptedData Id="ED1">
<enc:EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#kw-aes128"/>
<ds:KeyInfo>
<ds:RetrievalMethod
URI="#EK"
Type="http://www.w3.org/2001/04/xmlenc#EncryptedKey"/>
</ds:KeyInfo>
<enc:CipherData>
<enc:CipherReference
URI="EPUB/book.html"/>
</enc:CipherData>
</enc:EncryptedData>
<enc:EncryptedData Id="ED2">
<enc:EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#kw-aes128"/>
<ds:KeyInfo>
<ds:RetrievalMethod
URI="#EK" Type="http://www.w3.org/2001/04/xmlenc#EncryptedKey"/>
</ds:KeyInfo>
<enc:CipherData>
<enc:CipherReference
URI="EPUB/images/cover.png"/>
</enc:CipherData>
</enc:EncryptedData>
</encryption>
The contents of the EPUB/As_You_Like_It.opf
file
<?xml version="1.0"?>
<package
version="3.0"
xml:lang="en"
xmlns="http://www.idpf.org/2007/opf"
unique-identifier="pub-id">
<metadata
xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:identifier
id="pub-id">
urn:uuid:B9B412F2-CAAD-4A44-B91F-A375068478A0
</dc:identifier>
<dc:language>
en
</dc:language>
<dc:title>
As You Like It
</dc:title>
<dc:creator
id="creator">
William Shakespeare
</dc:creator>
<meta
property="dcterms:modified">
2000-03-24T00:00:00Z
</meta>
<dc:publisher>
Project Gutenberg
</dc:publisher>
<dc:date>
2000-03-24
</dc:date>
<meta
property="dcterms:dateCopyrighted">
9999-01-01
</meta>
<dc:identifier
id="isbn13">
urn:isbn:9780741014559
</dc:identifier>
<dc:identifier
id="isbn10">
0-7410-1455-6
</dc:identifier>
<link
rel="xml-signature"
href="../META-INF/signatures.xml#AsYouLikeItSignature"/>
</metadata>
<manifest>
<item id="r4915"
href="book.html"
media-type="application/xhtml+xml"/>
<item id="r7184"
href="images/cover.png"
media-type="image/png"/>
<item id="nav"
href="nav.html"
media-type="application/xhtml+xml"
properties="nav"/>
</manifest>
<spine>
<itemref
idref="r4915"/>
</spine>
</package>
The following are examples of allowed clock values:
5:34:31.396
= 5 hours, 34 minutes, 31 seconds, and 396 milliseconds
124:59:36
= 124 hours, 59 minutes, and 36 seconds
0:05:01.2
= 5 minutes, 1 second, and 200 milliseconds
0:00:04
= 4 seconds
09:58
= 9 minutes and 58 seconds
00:56.78
= 56 seconds and 780 milliseconds
76.2s
= 76.2 seconds = 76 seconds and 200 milliseconds
7.75h
= 7.75 hours = 7 hours and 45 minutes
13min
= 13 minutes
2345ms
= 2345 milliseconds
12.345
= 12 seconds and 345 milliseconds
This appendix registers the media type application/oebps-package+xml
for the EPUB
package document. This registration supersedes RFC4839 (see https://www.rfc-editor.org/rfc/rfc4839).
The package document is an XML file that describes an EPUB publication. It identifies the resources in the EPUB publication and provides metadata information. The package document and its related specifications are maintained and defined by the World Wide Web Consortium (W3C).
application
oebps-package+xml
None.
None.
8bit if UTF-8; binary if UTF-16.
Package documents are in XML, represented either in UTF-8 or UTF-16. When the package document is written in UTF-8, the file is 8bit compatible. When it is written in UTF-16, the binary content-transfer-encoding must be used. For further details, see [rfc7303].
Package documents contain well-formed XML conforming to the XML 1.0 specification.
Clearly, it is possible to author malicious files which, for example, contain malformed data. Most XML parsers protect themselves from such attacks by rigorously enforcing conformance.
All processors that read package documents should rigorously check the size and validity of data retrieved.
There is no current provision in the EPUB 3 specification for encryption, signing, or authentication within the package document format.
None.
This media type registration is for the EPUB package document, as described by the EPUB 3 specification located at https://www.w3.org/TR/epub-33/.
The EPUB 3 specification supersedes the Open Packaging Format 2.0.1 specification, which is
located at https://idpf.org/epub/20/spec/OPF_2.0.1_draft.htm and which also uses the application/oepbs-package+xml
media type.
This media type is in wide use for the distribution of ebooks in the EPUB format.
none
.opf
TEXT
EPUB Canonical Fragment Identifiers are custom fragment identifiers defined for EPUB Publications. They may be used to refer to an arbitrary content within any publication resource defined for the publication. These identifiers are defined at https://idpf.org/epub/linking/cfi/.
EPUB 3 Working Group (public-epub-wg@w3.org)
COMMON
World Wide Web Consortium (W3C)
This appendix registers the media type application/epub+zip
for the EPUB Open Container
Format (OCF).
An OCF ZIP container, or EPUB container, file is a container technology based on the zip archive format (see https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT). It is used to encapsulate the EPUB publication. OCF and its related standards are maintained and defined by the World Wide Web Consortium (W3C).
application
epub+zip
None.
None.
OCF ZIP container files are binary files encoded in the
application/zip
media type.
All processors that read OCF ZIP container files should rigorously check the size and validity of data retrieved.
In addition, because of the various content types that can be embedded in OCF ZIP container
files, application/epub+zip
may describe content that poses security
implications beyond those noted here. However, only in cases where the processor recognizes
and processes the additional content, or where further processing of that content is
dispatched to other processors, would security issues potentially arise. In such cases,
matters of security would fall outside the domain of this registration document.
Security considerations that apply to application/zip
also apply to OCF ZIP
container files.
None.
This media type registration is for the EPUB Open Container Format (OCF), as described by the
EPUB 3 specification located at https://www.w3.org/TR/epub-33/
.
The EPUB 3 specification supersedes both RFC 4839 and the Open Container
Format 2.0.1 specification, which is located at https://idpf.org/epub/20/spec/OCF_2.0.1_draft.doc
, and which also
uses the application/epub+zip
media type.
This media type is in wide use for the distribution of ebooks in the EPUB format.
0: PK 0x03 0x04
, 30: mimetype
, 38:
application/epub+zip
OCF ZIP container files are most often identified with the extension
.epub
.
ZIP
EPUB Canonical Fragment Identifiers are custom fragment identifiers defined for EPUB Publications. They may be used to refer to an arbitrary content within any publication resource defined for the publication. These identifiers are defined at https://idpf.org/epub/linking/cfi/.
EPUB 3 Working Group (public-epub-wg@w3.org)
COMMON
World Wide Web Consortium (W3C)
audio
§9.2.2.8body
§9.2.2.4collection
§5.8.1Compression
§4.2.6.3.2.2container
§4.2.6.3.1.1dc:contributor
§5.5.4.2dc:creator
§5.5.4.3dc:date
§5.5.4.4dc:identifier
§5.5.3.1dc:language
§5.5.3.3dc:subject
§5.5.4.5dc:title
§5.5.3.2dc:type
§5.5.4.6EncryptedData
§4.2.6.3.2.1EncryptedKey
§4.2.6.3.2.1encryption
§4.2.6.3.2.1epub:type
§C.2head
§9.2.2.2item
§5.6.2itemref
§5.7.2link
§5.5.7links
§4.2.6.3.1.4manifest
§5.6.1meta
§5.5.5metadata
§5.5.1package
§5.4par
§9.2.2.6rootfile
§4.2.6.3.1.3rootfiles
§4.2.6.3.1.2seq
§9.2.2.5signatures
§4.2.6.3.6.1smil
§9.2.2.1spine
§5.7.1text
§9.2.2.7a
element
area
element
base
element
bdo
element
canvas
element
content
attribute (for meta
element)
dir
attribute (for html-global
element)
div
element
embed
element
form
element
href
attribute (for a
element)
html
element
iframe
element
img
element
li
element
name
attribute (for meta
element)
object
type
ol
element
picture
element
role
attribute
rp
element
script
element
source
element
span
element
src
attribute (for source
element)
src
attribute (for img
element)
srcset
attribute (for source
element)
srcset
attribute (for img
element)
track
element
type
attribute (for source
element)
video
element
list
)
svg
element
title
element
This section is non-normative.
Note that this change log only identifies substantive changes since EPUB 3.2 — 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.
name
by
hasFeature
in an example. See issue 2543. dir
attribute under-implemented due to lack of support in
reading systems. See pull request
2515.viewport meta
tag. See pull request 2503.acquire
and xmp
properties after finding no
evidence these are used by publishers or reading systems. See issue 2489.epub:type
attribute is not allowed on the
head
element and metadata content in XHTML content documents. See issue 2486.viewport meta
tag definition. See
pull request 2457.viewport meta
height and width not
be declared multiple times. See issue
2442.epub:type
attribute usage
definitions. See issue 2434.href
attribute in the package document must not be
used to reference other package document elements (i.e., to indirectly reference a resource via
its manifest or spine entry). See issue
2420.text
element definition regarding using
embedded timed media. See issue
2397.epub:type
may be used has been
made explicit. See issue 2377.meta
element for specifying the initial containing
boundary in fixed-layout documents is now formally defined. See issue 2292. title
element is restricted to
HTML elements. See issue 2355.authority
property and
added a note referencing the old IDPF registry. See issue 2200.collection-type
values and replaced with a note about enabling improved handling of related
content. See issue 2071.epub:type
that suggest
equivalence with ARIA roles. See issue
2070.audio
element's definition by making it optional and adapted the
specification's text elsewhere to address the situation when the element is indeed not present.
See issue 1986.page-spread-center
property is now an alias for
spread-none
. See issue
1929.page-spread-center
. It is now an alias for
spread-none
. See issue
1929.base
element to the list of discouraged XHTML constructs.
See issue 1699.file
scheme should not be used on manifest items.
See issue 1688.link
element can be used to link individual
metadata properties in an alternative format. See issue 1666.application/ecmascript
as a core media type for scripts. See issue 1353.link
elements to
have core media type fallbacks. See issue 1312.direction
attribute in 6.3.1.2 CSS requirements. See issue
1614.requiredExtensions
attribute. See issue 1087.dc:creator
and dc:contributor
elements to have
multiple roles and allowed roles for publisher
. See issue 1129 and issue 1583container.xml
, encryption.xml
and
signatures.xml
files. All schemas are considered non-normative. See issue 1566.META-INF
directory. See issue 1205.refines
attribute use fragment identifiers
to reference publication resources. See issue 1361.par
and
seq
ordering match the default reading order to guidance. See issue 1458nav
elements without an epub:type
attribute are not subject to the EPUB navigation document's content model restrictions. See issue 976.dc:language
elements must be well-formed
language tags. See issue 1325.auto
value for dir
attribute and clarified the
precedence of the attribute. See issue
1491 and issue 1494.hreflang
attribute to link
elements to identify
the language of linked resources. See issue 1488.epub:type
attribute does not improve the
accessibility of publications. Added pointers to the role
attribute and the
DPUB-ARIA vocabulary for accessibility.toc nav
match the ordering of
EPUB content documents in the spine, and the elements within each file, has been reduced to a
recommendation. See issue 1283.script
elements that contain data blocks are not instances of scripting. See issue 1352.This section is non-normative.
Specifications, like art, are human creations. No human has done more for EPUB than Garth Conboy, who has been there every step of the way, from the very first OEB 1.0 in 1999 to today's EPUB 3.3. None of this would have happened without Garth's vision, knowledge, and preternatural good nature. We dedicate EPUB 3.3 to his memory. We are forever in your debt, Garth.
The following members of the EPUB 3 Working Group contributed to the development of this specification:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: