Copyright © 1999-2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
EPUB® 3 defines a distribution and interchange format for digital publications and documents. The EPUB format provides a means of representing, packaging, and encoding structured and semantically enhanced Web content — including HTML, CSS, SVG, and other resources — for distribution in a single-file container.
This specification defines the 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. Other documents may supersede this document. 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 Working Draft. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-epub-wg@w3.org (subscribe, archives).
Publication as a Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 15 September 2020 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 informative 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 the EPUB specifications through the central product they define: the EPUB Publication.
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 § 2.3 Package Document for the requirements for the Package Document.
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. Refer to § 4. EPUB Navigation Document for more information about this 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 § 3. EPUB Content Documents for detailed information about the rules and requirements to produce EPUB Content Documents, and [EPUB-A11Y-11] for accessibility requirements.
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 § 7. Media Overlays for the definition of Media Overlay Documents.
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 informative resources (/META-INF
). Key among these resources is the
container.xml
file, which directs Reading Systems to the available Package
Documents. Refer to § 6. Open Container Format for more information about the Container format.
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 informative [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 [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.
As HTML evolves, it is possible that previously-valid features may become obsolete or be removed. In general, however, the removal of features typically only occurs when serious issues arise with them (e.g., lack of support in browsers, security issues).
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.
As SVG evolves, features previously-valid features may become obsolete or be removed. The Working Group anticipates the W3C will make any such changes carefully to ensure minimal disruption, but in the case of a backwards-incompatible revision the Working Group could revisit the use of an undated reference.
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.
This specification relies on a subset of [SMIL3], from which the Media Overlays elements and attributes defined in § 7.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. They appear capitalized wherever used.
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.
The area within the Viewport dedicated to the display of EPUB Content Documents. The Content Display Area excludes any borders, margins, headers, footers, or other decoration a EPUB Reading System might inject into the Viewport.
In the case of synthetic spreads, the Viewport contains two Content Display Areas.
A Publication Resource that does not require the provision of a fallback (cf. Foreign Resource).
The ZIP-based packaging and distribution format for EPUB Publications defined in § 6.2 OCF ZIP Container.
EPUB Container and OCF ZIP Container are synonymous.
A Publication Resource with an XHTML or SVG media type that contains all or part of the content of an EPUB Publication (i.e., the textual, visual and/or audio content). These resources must conform to their respective XHTML or SVG definitions to be used in the spine or be referenced from another EPUB Content Document.
An EPUB Content Document is a Core Media Type Resource, so EPUB Creators can include it without the provision of fallbacks.
The person(s) or organization responsible for the creation of an EPUB Publication.
Depending on the process used to produce EPUB Publications, EPUB Creator may sometimes refer to responsibilities of the organization (e.g., the publisher) or the individuals preparing the publication (e.g., technical editors).
Previous versions of this specification referred to the EPUB Creator as the Author.
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 § 4. 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 name of any type of file within an OCF Abstract Container, whether a directory or a file within a directory.
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 § 5. Fixed Layouts.
A Publication Resource that is not a Core Media Type Resource. Foreign Resources are subject to the fallback requirements defined in § 2.2.1.3 Foreign Resources.
A resource that is located inside the EPUB Container.
Refer to § 2.2.2 Resource Locations for media type specific rules for resource locations.
The section of the Package Document that lists the Publication Resources.
Refer to § 2.3.2.4.1 The manifest
Element for more information.
An XML document that associates the XHTML Content Document with pre-recorded audio narration to provide a synchronized playback experience, as defined in § 7. 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 § 6.1 OCF Abstract Container.
A Publication Resource that describes the rendering of an EPUB Publication, as defined in § 2.3 Package Document. The Package Document carries meta information about the EPUB Publication, provides a manifest of resources and defines a default reading order.
For a given directory within the OCF Abstract
Container, the string holding all directory File Name in the full path
concatenated together with a /
(U+002F
) character separating the
directory File Names.
For a given file within the OCF Abstract Container, the Path Name is the string holding all
directory File Names concatenated together with a /
character separating the
directory File Names, followed by a /
character and then the File Name of the
file.
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 Document, CSS Style Sheets, audio, video, images, embedded fonts, and scripts.
EPUB Creators typically list Publication Resources in the Package Document manifest and bundle them in the EPUB Container, with the following exceptions:
they do not have to list resources encoded as data URLs in the manifest; and
they may locate resources listed in § 2.2.2 Resource Locations outside the EPUB Container.
Examples of resources that are not Publication Resources include those identified in Package
Document link
elements and those identified in
outbound hyperlinks that resolve to Remote Resources (e.g., referenced from the
href
attribute of an [HTML] a
element).
A resource that is located outside of the EPUB Container, typically, but not necessarily, online.
Refer to § 2.2.2 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 Reading System may or may not generate a physical root directory for the contents of the OCF Abstract Container if it unzips the contents.
An EPUB Content Document that includes scripting or an XHTML Content Document that contains [HTML] forms.
Refer to § 3.3.2 Scripting for more information.
An ordered list of Publication Resources in the Package Document, typically EPUB Content Documents, that represent the default reading order.
Refer to § 2.3.2.5.1 The spine
Element for more information.
An EPUB Content Document that conforms to the constraints expressed in § 3.2 SVG Content Documents.
The rendering of two adjacent pages simultaneously on a device screen.
An EPUB Content Document referenced from the spine, whether directly or via a fallback chain.
The primary identifier for an EPUB Publication in the Package Document, as
identified by the unique-identifier
attribute.
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 § 3.1 XHTML Content Documents.
XHTML Content Documents use the XHTML 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.
In Package Document metadata examples, reserved prefixes are used without declaration.
For convenience, the following namespace prefixes [XML-NAMES] are used in this specification without explicitly being declared. EPUB Creators MUST declare these prefixes to use them in an EPUB Content Document.
prefix | URI |
---|---|
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 § 2.3 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 § 6. Open Container Format.
In addition, all Publication Resources MUST adhere to the requirements in § 2.2 Publication Resources.
The rest of this specification covers specific conformance details.
This section is non-normative.
An EPUB Publication typically consists of many Publication Resources. These resources are divided into two categories: those that do not require fallbacks (Core Media Type Resources) and those that do (Foreign 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.
Inclusion as a Core Media Type Resource does not mean that all Reading Systems will support the rendering of a resource, however. Reading Systems 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.
Foreign Resources come with no guarantee of rendering support, which is why they require a fallback to a Core Media Type Resource. EPUB Publications should be fully consumable on any conforming Reading System, so providing a fallback is necessary to ensure that the use of Foreign Resources does not impact on the ability of the user to consume the content.
This section lists the set of Core Media Type Resources and identifies fallback mechanisms used to satisfy the consumability requirement.
EPUB also exempts some [HTML] elements from support requirements (see § 3.1.4.4 Foreign Resource Restrictions). Resources referenced from these elements are neither Core Media Type Resources nor Foreign Resources — they do not require fallbacks, but they also have no support requirements.
EPUB Creators may include Publication Resources that conform to the following MIME media type [RFC2046] specifications in EPUB Publications without fallbacks.
The columns in the following 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/opus
|
[RFC7845] | OPUS audio using OGG container |
Video | ||
EPUB 3 allows EPUB Creators to include any video codecs without fallbacks, although none are technically Core Media Type Resources. Although the Working Group recommends that Reading Systems support at least one of the H.264 [H264] and VP8 [RFC6386] video codecs, support is not a conformance requirement — a Reading System might support other video codecs, or none at all. EPUB Creators must consider factors such as breadth of adoption, video playback quality, and technology usage royalty requirements when making a choice to include video in either format, or both. | ||
Tracks | ||
EPUB Creators can include any kind of audio or video track (for example, [WebVTT] captions, subtitles and descriptions) without a fallback. Refer to § 3.1.4.4 Foreign Resource Restrictions for more information. | ||
Style | ||
text/css
|
CSS Style Sheets | CSS Style Sheets. |
Fonts | ||
EPUB 3 allows EPUB Creators to include any font resource without a fallback, as CSS already defines fallback rules for fonts. Refer to the Reading System support requirements for fonts [EPUB-RS-33] for more information. | ||
|
[TrueType] | TrueType fonts |
|
[OpenType] | OpenType fonts |
|
[WOFF] | WOFF fonts |
font/woff2
|
[WOFF2] | WOFF2 fonts |
Other | ||
application/xhtml+xml
|
XHTML Content Documents | XHTML Content Documents that use the XHTML syntax [HTML]. |
|
[RFC4329] | Scripts. |
application/x-dtbncx+xml
|
[OPF-201] | The legacy NCX. |
application/smil+xml
|
Media Overlays | EPUB Media Overlay documents |
Although, OPUS/OGG has good support in Android, MacOS, Windows, and Linux, Apple, starting with iOS 11, only supports the OPUS codec in a CAF container. The working group will monitor support for OPUS in iOS and may remove OPUS as a core media type if the level of support is inadequate.
WebP is currently not defined in a stable specification and its media type has not been registered with IANA. Apple also only supports WebP on macOS 11. The working group will continue to monitor these issues.
EPUB Creators MAY include Foreign Resources without fallbacks provided they:
do not reference the resources from spine
itemref
elements; and
do not embed them directly in EPUB Content Documents (e.g., via [HTML] embedded content and [SVG] image
and foreignObject
elements).
This exception allows EPUB Creators to include resources in the EPUB Container that are not for use by EPUB Reading Systems. The primary case for this exception 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).
When a Foreign Resource is included in the spine or directly rendered in its native format in an EPUB Content Document, a fallback Core Media Type Resource MUST be included. 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 fallbacks are a feature of the Package Document that create fallback chains
to Core Media Type Resources. They are used to create fallbacks for Foreign Resources in the
spine and when intrinsic fallback capabilities are not
available (e.g., for the [HTML] img
element).
Refer to the [HTML] and [SVG] specifications for the intrinsic fallback capabilities their elements provide.
EPUB Creators MUST locate all Publication Resources in the EPUB Container, with the following exceptions:
EPUB Creators should locate these resources inside the EPUB Container whenever feasible to allow users access to the entire presentation regardless of connectivity status.
The rules in this section for Publication Resource locations apply regardless of whether the given resource is a Core Media Type Resource or a Foreign Resource.
The inclusion of Remote Resources is indicated via the remote-resources
property on the manifest
item
element.
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 MAY use data URLs in EPUB Publications provided their use does not result in a Top-level Content Document or top-level browsing context [HTML]. This restriction applies to data URLs used in the following scenarios:
in manifest item
elements referenced from the
spine;
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
.
The list of prohibited uses for data URLs is subject to change as the respective standards that allow their use evolve.
This restriction on their use is to prevent security issues and also to ensure that Reading Systems can determine where to take a user next (i.e., because these resources are not be listed in the spine).
Resources represented as data URLs are not Publication Resources so are exempt from the requirement for EPUB Creators to list them in the manifest.
EPUB Creators MUST encode Data URLs as Core Media Types or use them where they can provide a fallback (i.e., Data URLs are subject to the foreign resource restrictions).
Any Publication Resource that is an XML-Based Media Type:
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.
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 metadata.
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 Package.
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 § 6.1.5.2.1 Container File (container.xml
)
Refer to § H.1 The application/oebps-package+xml
Media Type for information about the file
properties of Package Documents.
All [XML] elements defined in this section are in the http://www.idpf.org/2007/opf
namespace [XML-NAMES] unless otherwise specified.
package
ElementThe package
element is the root element of the Package Document.
package
The package
element is the root element 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 dc:identifier
element that provides the preferred, or primary,
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.
metadata
ElementThe 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]
DCMES 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 link
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.
In keeping with this philosophy, the Package Document only has
the following minimal metadata requirements: it MUST contain the [DCTERMS] title
, identifier
, and language
elements together with the
[DCTERMS] modified
property. All other
metadata is OPTIONAL.
The meta
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.
See [EPUB-A11Y-11] for accessibility metadata recommendations.
The Dublin Core elements [DCTERMS] and meta
element have mandatory child text
content [DOM]. This specification refers to this content as the
value of the element in their descriptions.
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 are not significant. Sequences of one or more whitespace characters are collapsed to a single space [Infra] during processing .
identifier
ElementThe [DCTERMS] identifier
element contains an identifier such as a
UUID, DOI or ISBN.
dc:identifier
http://purl.org/dc/elements/1.1/
REQUIRED child of 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
identifier
element. This identifier
element MUST
specify an id
attribute whose value is referenced from the package
element's
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 an identifier
conforms to an
established system or an issuing authority granted it.
title
ElementThe [DCTERMS] title
element represents an instance of a name for the
EPUB Publication.
dc:title
http://purl.org/dc/elements/1.1/
REQUIRED child of metadata
.
Text
The metadata
section MUST contain at least one title
element containing the title for the EPUB Publication.
The first 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 title
element to ensure
consistent rendering of the title in Reading Systems.
Although it is possible to include more than one title
element for
multipart titles, Reading System support for additional 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 xmlns:dc="http://purl.org/dc/elements/1.1/">
<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 xmlns:dc="http://purl.org/dc/elements/1.1/">
<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.
language
ElementThe [DCTERMS] language
element specifies the language of the content
of the EPUB Publication.
dc:language
http://purl.org/dc/elements/1.1/
REQUIRED child of metadata
. Repeatable.
id
[optional]
Text
The metadata
section MUST contain at least one language
element. The value of each language
element MUST be a well-formed
language tag [BCP47].
Although EPUB Creators MAY specify additional language
elements for
multilingual Publications, Reading Systems will treat the first
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 identifier
, language
, and title
are designated as OPTIONAL. These elements conform
to the following generalized definition:
contributor
| coverage
| creator
|
date
| description
| format
|
publisher
| relation
| rights
|
source
| subject
| type
http://purl.org/dc/elements/1.1/
OPTIONAL child of metadata
. Repeatable.
Text
This specification does not modify the [DCTERMS] element definitions except as noted in the following sections.
contributor
ElementThe [DCTERMS] contributor
element 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 contributor
element are identical to those for
the creator
element in all other
respects.
creator
ElementThe [DCTERMS] creator
element represents the name of a person,
organization, etc. responsible for the creation of the content. EPUB Creators can associate a role
property with the element to indicate the function the creator played.
The 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 creator
element.
The document order of creator
elements in the metadata
section determines the display priority, where the first creator
element encountered is the primary creator.
EPUB Creators SHOULD represent secondary contributors using the contributor
element.
date
ElementThe [DCTERMS] date
element MUST only be used to define 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 date
element.
subject
ElementThe [DCTERMS] subject
element 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
subject
element that does not specify a scheme.
The values of the subject
element and term
property
are case sensitive only when the designated scheme requires.
type
ElementThe [DCTERMS] type
element 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 an informative registry of specialized EPUB Publication types for use with this element. This Working Group no longer maintains this registry and does not anticipate developing new specialized publication types.
meta
ElementThe meta
element provides a generic means of including package metadata.
meta
As child of the metadata
element. Repeatable.
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 DCMES [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 metadata
section MUST contain exactly one
[DCTERMS] modified
property 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.
link
ElementThe link
element associates resources with an EPUB Publication, such
as metadata records.
link
As a child of metadata
. Repeatable.
href
[required]
hreflang
[optional]
id
[optional]
media-type
[conditionally required]
properties
[optional]
refines
[optional]
rel
[required]
Empty
The metadata
element MAY contain zero or
more link
elements, each of which identifies the location of a linked
resource in its REQUIRED href
attribute
Linked Resources 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 JSON-LD [JSON-LD11] embedded in an
[HTML] script
element).
In all other cases (e.g., when linking to standalone [ONIX] or [XMP] records), the linked resources 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 locally or remotely, but should consider that Reading Systems are not required to retrieve to Remote Resources (i.e., Reading Systems might not make Remote Resources available).
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 Local Resources.
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 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, the properties
attribute can specify a semantic
identifier.
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 to enhance the information available to Reading Systems, but Reading Systems may ignore these records.
When a Reading System processes linked records [EPUB-RS-33], the document order of
link
elements is used to determine which has the highest priority in
the case of conflicts (i.e., first in document order has the highest priority).
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.
manifest
ElementThe manifest
element provides an exhaustive list of Publication
Resources used in the rendering of the content.
EPUB Creators MUST list all Publication Resources
in the manifest
, regardless of whether they are Local or Remote Resources, using item
elements.
Note that the manifest
is not self-referencing: EPUB Creators MUST NOT
specify an item
element that refers to the Package Document itself.
Failure to provide a complete manifest of resources may lead to rendering issues. Reading Systems might not unzip such resources or could prevent access to them for security reasons.
This specification supports internationalized resource naming, so elements and attributes that reference Publication Resources accept URLs [URL] as their value. For compatibility with older Reading Systems that only accept URIs, EPUB Creators should restrict resource names to the ASCII character set.
item
ElementThe item
element represents a Publication Resource.
item
As a child of manifest
. Repeatable.
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. EPUB Creators MAY use absolute- or relative-URL string
[URL], but they MUST ensure each URL is unique within the manifest
scope
after resolution
to an absolute URL [EPUB-RS-33].
The Publication Resource identified by an item
element MUST conform to the applicable specification(s) as inferred from the MIME media
type provided in the media-type
attribute. For Core Media Type Resources, EPUB Creators MUST use the media
type designated in § 2.2.1.2 Supported Media Types.
The fallback
attribute takes an IDREF [XML]
that identifies a fallback for the Publication Resource referenced from the
item
element. EPUB Creators MAY provide fallbacks for Core Media
Type Resources (e.g., to provide a static alternative to a Scripted Content
Document). Refer to § 2.3.2.4.3 Manifest Fallbacks for
fallback requirements for Foreign Resources.
The Manifest 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.
EPUB Creators MUST declare all applicable descriptive metadata properties for each Publication Resource in this attribute (e.g., if the resource is the cover image, contains scripting, or references remote resources).
EPUB Creators MUST declare exactly one item
as the EPUB Navigation
Document using the nav
property.
The media-overlay
attribute takes an IDREF
[XML] that identifies the Media Overlay Document for the resource described by
this item
. Refer to § 7.3.5 Media Overlays Packaging for more
information.
The order of item
elements in the manifest
is not
significant. The spine
element provides the presentation sequence of content documents.
EPUB Creators MAY reference Foreign Resources in contexts in which an intrinsic fallback
cannot be provided (e.g., directly from spine
itemref
elements; from [HTML]
img
, iframe
and link
elements in XHTML
Content Documents; and from @import
rules in CSS Style Sheets).
EPUB Creators MUST provide manifest fallbacks in such cases.
The fallback
attribute on the
manifest
item
element specifies the fallback for
the referenced Publication Resource. The fallback
attribute's IDREF [XML]
value MUST resolve to another item
in the manifest
. This
fallback item
MAY itself specify another fallback item
, and so
on.
The ordered list of all the ID references that a Reading System can reach, starting from
a given item's fallback
attribute, represents the fallback chain
for that item. The order of the resources in the fallback chain represents the EPUB
Creator's preferred fallback order.
Fallback chains MUST conform to one of the following requirements, as appropriate:
For Foreign Resources referenced directly from spine itemref
elements, the chain
MUST contain at least one EPUB Content Document.
For Foreign Resources for which an EPUB Creator cannot provide an intrinsic fallback, the chain MUST contain at least one Core Media Type Resource.
Fallback chains MUST NOT contain circular or self-references to item
elements in the chain.
EPUB Creators MAY provide fallbacks for Top-Level Content Documents that are EPUB Content Documents (e.g., to provide fallbacks for scripted content).
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.
bindings
Element (Deprecated)The bindings
element defines a set of custom handlers for media types not
supported by this specification. Its use is deprecated.
Refer to [EPUBPublications-301] for more information about this element.
spine
ElementThe 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 Publication
Resource.
EPUB Creators MUST list in the spine
all
Publication Resources 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 Publication Resources hyperlinked from hyperlinked
Publication Resources, and so on.).
EPUB Creators also MUST list in the spine
all Publication Resources
hyperlinked to from the EPUB Navigation Document, regardless of whether EPUB
Creators include the Navigation Document in the spine
.
As Remote Resources referenced from hyperlinks are not Publication Resources, they are not subject to the requirement to include in the spine (e.g., Web pages and resources).
Embedded Publication Resources (e.g., via the [HTML] iframe
element) must not be listed 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 Content Documents and parts of Content Documents MAY override this
setting (e.g., via the writing-mode
CSS property). Reading Systems can 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.
itemref
ElementThe itemref
element identifies a Publication Resource in the default
reading order.
itemref
As a child of spine
. Repeatable.
id
[optional]
idref
[required]
linear
[optional]
properties
[optional]
Empty
Each itemref
element MUST reference the ID
[XML] of a unique item
in the
manifest via the IDREF [XML] in its idref
attribute (i.e., two
or more itemref
elements cannot reference the same item
).
Each referenced manifest item
MUST be either a)
an EPUB Content Document or b) another type of Publication Resource which,
regardless of whether it is a Core Media Type Resource or a Foreign
Resource, MUST include an EPUB Content Document in its 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.
The spine MUST contain at least one linear
itemref
element — whose linear
attribute value is
either explicitly or implicitly set to "yes
". Reading Systems will assume
the value "yes
" for itemref
elements without a
linear
attribute.
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.
collection
ElementThe 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.
The collection
element, as defined in this section, represents a generic
framework from which specializations are intended to be derived (e.g., through EPUB
sub-specifications). Such specializations MUST define the purpose of the
collection
element, as well as all requirements for its valid
production and use (specifically any requirements that differ from the general framework
presented below).
Each specialization MUST define a role value that uniquely
identifies all conformant collection
elements. 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].
This specification reserves the use of NMTOKEN values for roles defined in EPUB specifications. NMTOKEN values not defined by a recognized specification are not valid. This section does not define any roles.
Third parties MAY define custom roles for the collection
element, but they
MUST identify such roles using absolute-URL-with-fragment strings [URL]. Custom roles MUST NOT incorporate
the string "idpf.org
" in the host component [URL] of their
identifying URL.
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 and does not anticipate defining new types of collections.
The OPTIONAL metadata
element child of
collection
is an adaptation of the package metadata
element, with the following
differences in syntax and semantics:
No metadata is mandatory by default.
All primary metadata expressions apply to the
collection
.
The refines
attribute MUST NOT
reference elements outside the containing collection
.
The metadata
element MUST NOT contain OPF2
meta
elements.
EPUB specifications that implement collections MAY override package-level restrictions on the use of metadata elements.
A collection
MAY define sub-collections through the inclusion of one or more
child collection
elements.
The link
element child of
collection
is an adaptation of the metadata link
element, with the following differences in syntax and
semantics:
The rel
attribute is OPTIONAL.
The properties
attribute also accepts manifest item
properties
without a prefix (e.g., so that a collection can declare its own Navigation
Document or cover image).
EPUB Creators MUST NOT specify the refines
attribute.
Each link
element MUST reference a resource that is a member of the group.
The order of link
elements is not significant.
Specializations of the collection
element MAY tailor the requirements
defined above to better reflect their needs (e.g., requiring metadata, imposing further
restrictions on the use of elements and attributes, or making the order of
link
elements significant). However, the resulting content model MUST
represent a valid subset of the one defined in this section (e.g., specializations
cannot introduce new elements or attributes, or re-introduce those expressly forbidden
above). Specializations MUST NOT define collections in a way that overrides the
requirements of the manifest
and spine
.
The rendering of an EPUB Publication MUST NOT be dependent on the recognition of
collection
elements. The content MUST remain consumable by a user
without any information loss or other significant deterioration.
meta
ElementThe meta
element [OPF-201] is a legacy
feature that previously provided a means of including generic metadata. The EPUB 3 meta
element, which uses different attributes
and requires text content, replaces this attribute.
For more information about the meta
element, refer to its definition in
[OPF-201].
The [OPF-201] meta
element is retained in EPUB 3 primarily so that
EPUB Creators can identify the cover image for compatibility with EPUB 2 Reading
Systems. In EPUB 3, the cover image must be identified using the cover-image
property on the manifest item
for the image.
guide
ElementThe guide
element [OPF-201] is a legacy
feature that previously provided machine-processable navigation to key structures. The
landmarks nav in the EPUB Navigation
Document replaces this element.
For more information about the guide
element, refer to its definition in
[OPF-201].
The NCX [OPF-201] is a legacy feature that previously provided the table of contents. The EPUB Navigation Document replaces this document.
For more information about the NCX, refer to its definition in [OPF-201].
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.
An XHTML Content Document:
MUST be an [HTML] document that conforms to the XHTML syntax.
MUST conform to the conformance criteria for all document constructs defined by [HTML] unless explicitly overridden in § 3.1.4 HTML Deviations and Constraints.
MAY include extensions to the [HTML] grammar as defined in § 3.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 epub:type
attribute in XHTML Content Documents to express structural semantics.
As the [HTML] head
element contains metadata for the document, structural
semantics expressed on this element or any descendant of it have no meaning.
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 switch
element is deprecated. Refer to its
definition in [EPUBContentDocs-301] for usage information.
epub:trigger
Element (Deprecated)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 trigger
element is deprecated. Refer to its
definition in [EPUBContentDocs-301] for usage information.
EPUB Creators MAY specify custom attributes [EPUB-RS-33] in XHTML Content Documents to take advantage of Reading System-specific functionality not defined in this specification.
Custom attributes MAY be specified on any element in an XHTML Content Document.
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.
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
.
EPUB Creators MUST NOT include elements and attributes marked as deprecated in [MATHML3] within MathML markup in XHTML Content Documents.
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 § 3.2.3 Restrictions on SVG.
The svg
property of the manifest
item
element indicates that an XHTML Content
Document contains embedded SVG.
This section is non-normative.
base
Element 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
elements may
inadvertently result in references to Remote Resources, i.e., resources that are
outside the EPUB Container. Using the base
element in an EPUB
Publication may cause Reading Systems to misinterpret the location of resources
(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.
rp
ElementThe [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.
embed
ElementSince the [HTML] embed
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.
EPUB Creators MAY reference Foreign Resources from elements that have intrinsic fallback mechanisms, where an intrinsic fallback method is the capability to offer an alternative presentation if Reading Systems do not support the foreign resource. For example, most [HTML] embedded content elements provide options for alternative rendering, such as allowing multiple sources to be specified or allowing embedded HTML content for when user agents cannot render a resource. When referencing a Foreign Resource, EPUB Creators MUST provide a Core Media Type Resource or embedded HTML content via the given element's intrinsic fallback mechanism.
EPUB Creators MAY embed [HTML] flow content
within the audio
and video
elements for rendering in older Reading Systems that do not
recognize these elements (e.g., EPUB 2 Reading Systems), but it does not represent a
fallback Core Media Type Resource.
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 a media type in its type
attribute that is not a Core
Media Type.src
and
srcset
attributes provided EPUB Creators define a manifest fallback.EPUB Creators MAY reference Foreign Resources from the following [HTML] elements without providing a fallback Core Media Type Resource:
Refer to manifest fallbacks for the
provision of fallbacks for elements without intrinsic mechanisms, such as the [HTML]
iframe
.
Reading Systems may not support all the features of [SVG] or supported 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 § 3.1.4.2 Embedded SVG for the conformance requirements for SVG embedded in XHTML Content Documents.
An SVG Content Document:
MUST be a conforming SVG stand-alone file [SVG] and conform to all content conformance constraints expressed in § 3.2.3 Restrictions on SVG.
MAY specify the epub:type
attribute for expressing structural semantics and use 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 § 3.1.2 XHTML Requirements.
The [SVG] title
element MUST contain only valid XHTML Content Document Phrasing
content.
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 § 3.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 may not implement, or
may switch off, CSS processing. EPUB Creators must use the following format-specific
methods when they need control over these aspects of the rendering:
the dir
attribute [HTML] and direction
attribute [SVG] for inline base
directionality.
the bdo
element with the dir
attribute [HTML] and the presentation attribute alternative for unicode-bidi
[SVG] for bidirectionality.
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 an Appendix.
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.
In some cases, the unprefixed versions of these properties now support additional values. Reading Systems MAY support these values even with the prefixed property.
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 when they contain instances of [HTML] forms.
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 [URL] 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 Conformance [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
; andWhether EPUB Creators embed the code directly in the 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 § G.1 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 a parent 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 parent 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-layouts EPUBs is optional.
EPUB Creators should ensure container-constrained scripts degrade gracefully in Reading Systems without scripting support (see § 3.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.
EPUB documents, 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 MAY use 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 itemref
when rendering).
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 § 5. Fixed Layouts.
The rendition:layout
property MUST NOT be declared more than once.
EPUB Creators MAY specify the following properties locally on
spine itemref
elements to override the global value for the given spine item:
EPUB Creators MAY use only 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 meta
element, it indicates that the intended orientation applies globally (i.e., for all spine
items).
EPUB Creators MAY use 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.
EPUB Creators MAY specify the following properties locally on
spine itemref
elements to override the global value for the given spine item:
EPUB Creators MAY use only 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 MAY use the following values with the rendition:spread
property:
Do not incorporate spine items in a Synthetic Spread.
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.
The rendition:spread
property MUST NOT be declared more than once.
When Synthetic Spreads are used in the context of HTML 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 spine for information about declaration of global flow
directionality using the page-progression-direction
attribute and that of local
page-progression-direction within content documents.
EPUB Creators MAY specify the following properties locally on
spine itemref
elements to override the global value for the given spine item:
spread-portrait
property is deprecated. Refer
to its definition in [EPUBPublications-301] for more information.EPUB Creators MAY use only 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 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 specifies the forced placement of a
Content Document in a Synthetic Spread. rendition:page-spread-left
rendition:page-spread-left
property is an alias for the page-spread-left
property.rendition:page-spread-right
rendition:page-spread-right
property is an alias for the page-spread-right
property.The rendition:page-spread-left
property indicates that the given spine item is to be
rendered in the left-hand slot in the spread, and rendition:page-spread-right
that
it be rendered in the right-hand slot. The rendition:page-spread-center
property
indicates to override the synthetic spread mode and render a single viewport positioned at the
center of the screen.
The rendition:page-spread-left
, rendition:page-spread-right
and
rendition:page-spread-center
properties apply to both pre-paginated and
reflowable content, and 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
rendered 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 MAY only declare one page-spread-*
property on any given spine
item.
The rendition:page-spread-left
and rendition:page-spread-right
properties are aliases for the page-spread-left
and page-spread-right
properties. They 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
Working Group is not going to extend the EPUB Spine
Properties Vocabulary to add an unprefixed page-spread-center
property.
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 its 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] dimensions MUST be expressed in a viewport
meta
tag using the syntax defined in [CSS-Device-Adapt-1].
For SVG Fixed-Layout Documents, the initial containing block [CSS2] dimensions MUST
be expressed using the viewBox
attribute [SVG].
This section is non-normative.
The OCF Abstract Container file system model uses a single common Root Directory for all the contents. All Local Resources for the EPUB Publication 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 the Package Document(s) 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 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 § 6.1.5 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 § 6.1.5 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 § 6.2 OCF ZIP Container.
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.
Files within the OCF Abstract Container MUST reference each other via relative-URL-with-fragment strings [URL].
The relevant language specification for a given file format determines the base URL [URL] used to parse relative-URL-with-fragment strings [URL]. For example, CSS defines how relative URL references work in the context of CSS style sheets and property declarations [CSSSnapshot].
Unlike most language specifications, the base URL [URL] for all files within the META-INF
directory is the
Root Directory of the OCF Abstract Container.
For example, if META-INF/container.xml
has the following content:
<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
<rootfiles>
<rootfile full-path="EPUB/Great_Expectations.opf"
media-type="application/oebps-package+xml" />
</rootfiles>
</container>
then the path EPUB/Great_Expectations.opf
is relative to the root directory for the
OCF Abstract Container and not relative to the META-INF
directory.
All relative-URL-with-fragment strings [URL] MUST, after parsing to URL records [URL], identify resources within the OCF Abstract Container (i.e., at or below the Root Directory).
In the context of the Abstract Container, Path Names and File Names are case sensitive.
In addition, the following restrictions are designed to allow Path Names and File Names to be used without modification on most operating systems:
Path and File Names MUST be UTF-8 [Unicode] encoded.
The Path Name 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
)
Tags and Variation Selectors Supplement (U+E0000 … U+E0FFF
)
Supplementary Private Use Area-A (U+F0000 … U+FFFFF
)
Supplementary Private Use Area-B (U+100000 … U+10FFFF
)
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.
Some commercial ZIP tools do not support the full Unicode range for File Names. EPUB Creators who want to use ZIP tools that have these restrictions may find it best to restrict their File Names to the [US-ASCII] range.
META-INF
DirectoryAll 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 § 6.1.5.2 Reserved Files.
container.xml
)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.
container
ElementThe container
element is the root element of the
container.xml
file.
rootfiles
ElementThe rootfiles
element contains a list of Package Documents
available in the EPUB Container.
rootfile
ElementEach rootfile
element identifies the location of one Package
Document in the EPUB Container.
rootfile
As child of the rootfiles
element. Repeatable.
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.
links
ElementThe links
element identifies resources
necessary for the processing of the OCF ZIP Container.
links
OPTIONAL second child of container
. Repeatable.
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
Element
link
As child of the links
element.
Repeatable.
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 following example shows a sample container.xml
file for an EPUB
Publication with the root file EPUB/My Crazy Life.opf
(the Package
Document):
<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
<rootfiles>
<rootfile full-path="EPUB/My_Crazy_Life.opf"
media-type="application/oebps-package+xml" />
</rootfiles>
</container>
encryption.xml
)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
element
encryption
urn:oasis:names:tc:opendocument:xmlns:container
Root element 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 resources referenced by an EPUB Publication to make them more
difficult to extract for unrestricted use (e.g., fonts). Although obfuscation is not
encryption, Reading Systems use the encryption.xml
file in conjunction
with the resource obfuscation algorithm to
identify resources to de-obfuscated.
EPUB Creators MUST NOT encrypt or obfuscate 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 a 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
manifest.xml
)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.
metadata.xml
)EPUB Creators MUST use the OPTIONAL metadata.xml
file in the
META-INF
directory 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 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.
rights.xml
)This specification resrves the OPTIONAL rights.xml
file in the
META-INF
directory for digital rights management (DRM) information for
trusted exchange of EPUB Publications among rights holders, intermediaries, and
users.
This version of the specification does not require a specific format for DRM information,
but a future version might. EPUB Creators SHOULD only use namespace-qualified elements
[XML-NAMES] in the rights.xml
file to avoid collision with a future
format.
When EPUB Creators do not include a rights.xml
file, no part of the
container is rights governed at the container level. Rights expressions might exist
within the EPUB Publications.
If EPUB Creators do not include a rights.xml
file, no part of the OCF
Abstract Container is rights governed.
signatures.xml
)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
element
signatures
urn:oasis:names:tc:opendocument:xmlns:container
Root element 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 container at the container level. Digital signing might
exist within the EPUB Publication.
When an EPUB Creator creates a data signature for the 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 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
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 preexisting 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 the 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 § 6.1.5.2.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, and MUST NOT
include an extra field in its ZIP header.Refer to § H.2 The application/epub+zip
Media Type for further information about the
application/epub+zip
media type.
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 resources 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 ZIP archive 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 the font, some font vendors might only allow use of their fonts in EPUB Publications if those 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 such resources. 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 resources.
Note this specification does not claim that this constitutes encryption, nor does it guarantee that the resource will be secure from copyright infringement. The hope is that this algorithm will meet the requirements of most vendors who require some assurance that their resources cannot simply be extracted by unzipping the Container.
In the case of fonts, the primary use case for obfuscation, the defined mechanism will simply provide a stumbling block for those who are unaware of the license details. It will not prevent a determined user from gaining full access to the font. Given an OCF Container, it is possible to apply the algorithms defined to extract the raw font file. Whether this method of obfuscation satisfies the requirements of individual font licenses remains a question for the licensor and licensee.
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 SHOULD 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 resource consists of modifying the first 1040 bytes (~1KB) of the file. (In the unlikely event that the 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 resource, the result of performing a logical exclusive or (XOR) on the first byte of the raw 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 resources before compressing and adding them to the OCF Container.
Note that as obfuscation is not encryption, this requirement is not a violation of the one in § 6.1.5.2.2 Encryption File (encryption.xml
) to compress resources before encrypting
them.
Although not technically encrypted data, all obfuscated resources MUST have an entry in the encryption.xml
file accompanying the EPUB Publication (see § 6.1.5.2.2 Encryption File (encryption.xml
)).
EPUB Creators MUST specify an EncryptedData
element for each obfuscated resource.
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 resource in the CipherReference
child of the CipherData
element.
To prevent trivial copying of the embedded resource to other EPUB Publications, EPUB Creators
MUST NOT provide the obfuscation key in the
encryption.xml
file.
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 § F.3 Media Overlays Schema and conform to all content conformance constraints expressed in § 7.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.
SHOULD use semantic markup where appropriate.
All elements [XML] defined in this section are in the https://www.w3.org/ns/SMIL
namespace [XML-NAMES] unless otherwise specified.
smil
ElementThe smil
element is the root element of all Media Overlay Documents.
smil
The smil
element is the root element of the Media Overlay Document.
version
[required]
Specifies the version number of the [SMIL3] specification to which the Media Overlay 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 § 7.3.3 Structural Semantics in Overlays for more information.
In this order:
head
ElementThe head
element is the container for metadata in the Media Overlay
Document.
head
The head
element is the OPTIONAL first child of the smil
element.
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.
metadata
ElementThe 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 head
element.
None
[0 or more]
elements from any namespace
This specification defines no metadata properties that MUST occur in the Media Overlay
Document; the metadata
element is provided for custom metadata
requirements.
body
ElementThe body
element is the starting point for the presentation contained in the
Media Overlay Document. It contains the main sequence of par
and
seq
elements.
body
The body
element is the REQUIRED second child of the smil
element.
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 § 7.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]
Identifies an associated fragment of an EPUB Content Document.
The value MUST be a relative-URL-with-fragment string [URL] with a fragment identifier.
In any order:
MUST include at least one par
or seq
.
seq
ElementThe seq
element contains a sequential rendering of media objects.
seq
One or more seq
elements MAY occur as children of the body
element and of the seq
element.
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 § 7.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]
Identifies an associated fragment of an EPUB Content Document.
The value MUST be a relative-URL-with-fragment string [URL] with a fragment identifier.
Refer to § 7.3.2.1 Overlay Structure for more information.
In any order:
MUST include at least one par
or seq
.
par
ElementThe par
element defines the parallel rendering of media objects.
par
One or more par
elements MAY occur as children of the body
and seq
elements.
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 § 7.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 audio
element is OPTIONAL only if
its sibling text
element refers to
audio or video media (see § 7.3.2.4 Embedded Media), or to textual content
intended for rendering via text-to-speech.
text
ElementThe text
element references an element in the EPUB Content Document. A
text
element typically refers to a textual element but can also refer to
other EPUB Content Document media elements (see § 7.3.2.4 Embedded Media).
text
As a REQUIRED child of the par
element.
src
[required]
Identifies the associated fragment of an EPUB Content Document.
The value MUST be a relative-URL-with-fragment string [URL] with a fragment identifier.
id
[optional]
The ID [XML] of the element, which MUST be unique within the document scope.
Empty
audio
ElementThe audio
element represents a clip of audio media.
audio
A REQUIRED child of the par
element
unless its sibling text
element refers
to audio or video media, or to textual content intended for rendering via text-to-speech, in which case it is OPTIONAL (see § 7.3.2.4 Embedded Media).
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 § G.3 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 § G.3 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 body
(used for the main sequence), seq
(sequence) and par
(parallel). (Refer to § 7.2.2 Media Overlay Document Definition for more information on these and other
SMIL elements.)
The par
element is the basic building block of an 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 audio
element and a text
element. Since par
elements render their children in parallel, Reading Systems play
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 the Media Overlay, 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 § 7.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.
The body
of a Media Overlay Document consists
of two elements: the par
element and the seq
element. The ordering of these elements
represents how Reading Systems render the content in the corresponding EPUB Content
Documents during playback.
The par
element represents phrases. Each element identifies a text and audio
component to synchronize during playback.
The seq
element represents sequences. EPUB Creators can use it to represent
nested containers such as sections, asides, headers, 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 following example shows a Media Overlay Document with nested seq
elements, representing a chapter with both a section header and a figure.
<smil xmlns="http://www.w3.org/ns/SMIL" xmlns:epub="http://www.idpf.org/2007/ops" version="3.0">
<body>
<!-- a chapter -->
<seq id="id1" epub:textref="chapter1.xhtml#sectionstart" epub:type="chapter">
<!-- the section title -->
<par id="id2">
<text src="chapter1.xhtml#section1_title"/>
<audio src="chapter1_audio.mp3"
clipBegin="0:23:23.84"
clipEnd="0:23:34.221"/>
</par>
<!-- some sentences in the chapter -->
<par id="id3">
<text src="chapter1.xhtml#text1"/>
<audio src="chapter1_audio.mp3"
clipBegin="0:23:34.221"
clipEnd="0:23:59.003"/>
</par>
<par id="id4">
<text src="chapter1.xhtml#text2"/>
<audio src="chapter1_audio.mp3"
clipBegin="0:23:59.003"
clipEnd="0:24:15.000"/>
</par>
<!-- a figure -->
<seq id="id7" epub:textref="chapter1.xhtml#figure">
<par id="id8">
<text src="chapter1.xhtml#photo"/>
<audio src="chapter1_audio.mp3"
clipBegin="0:24:18.123"
clipEnd="0:24:28.764"/>
</par>
<par id="id9">
<text src="chapter1.xhtml#caption"/>
<audio src="chapter1_audio.mp3"
clipBegin="0:24:28.764"
clipEnd="0:24:50.010"/>
</par>
</seq>
<!-- more sentences in the chapter (outside the figure) -->
<par id="id12">
<text src="chapter1.xhtml#text3"/>
<audio src="chapter1_audio.mp3"
clipBegin="0:25:45.515"
clipEnd="0:26:30.203"/>
</par>
<par id="id13">
<text src="chapter1.xhtml#text4"/>
<audio src="chapter1_audio.mp3"
clipBegin="0:26:30.203"
clipEnd="0:27:15.000"/>
</par>
</seq>
</body>
</smil>
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 § 7.4 Skippability and Escapability), or customizing
the reading mode to suit structures such as tables.
The epub:textref
attribute and the text
element's
src
attribute both require a fragment identifier that references a specific
fragment (e.g., an element or text string) of the associated EPUB Content
Document.
For XHTML and SVG Content Documents, the fragment SHOULD be a reference to a target element [HTML] 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 text
elements'
src
attributes. For example, when referencing target elements [HTML], 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
elements 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.
Any EPUB Content Document associated with a Media Overlay MAY contain embedded media
such as video, audio, and images. EPUB Creators MAY use the Media Overlay text
element in such instances to reference
the embedded media by its element's id
attribute value.
When a text
element references embedded audio or video, the audio
sibling element is OPTIONAL.
Reading Systems will intiate playback of the media in the absence of an
audio
element.
EPUB Creators SHOULD avoid using scripts to control playback of referenced embedded EPUB Content Document media, as this might conflict with Media Overlays playback behavior.
EPUB Creators should carefully examine any overlapping audio situations and deal with them at the production stage, as Reading Systems handling of simultaneous volume levels is optional.
When a text
element references an embedded image, the audio
sibling element is OPTIONAL. In
the absence of an audio
element, Reading Systems will voice the image using
Text-to-Speech rendering.
EPUB Creators MUST ensure they provide fallback text for an image when an omitting an
audio
element (e.g., using the [HTML] alt
attribute).
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.
A Media Overlay par
element MAY omit an audio
element when its text
element references text or an image. In
these cases, Reading Systems are expected to render the referenced fragment via TTS, so EPUB
Creators MUST ensure the fragment is appropriate for TTS rendering (e.g., contains a textual
EPUB Content Document element or has a text fallback).
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 epub:type
attribute on par
, seq
, and body
elements.
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 Overlays 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 link to the CSS style sheet with the class definitions. Reading Systems might provide their own styling, or no styling at all, in the absence of a linked definition.
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, then
its manifest
item
element MUST specify a
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 meta
element with the duration
property.
In addition, EPUB Creators MUST provide the duration of each Media Overlay Document. EPUB
Creators may 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.
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.
The following non-exhaustive list represents terms from the Structural Semantics Vocabulary for which Reading Systems may offer the option of skippability:
footnote
endnote
pagebreak
Reading System are not required to support for skippability based on epub:type
values.
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).
The following non-exhaustive list represents terms from the Structural Semantics Vocabulary for which Reading Systems may offer the option of escapability:
table
table-row
table-cell
list
list-item
figure
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 EPUB Accessibility standard. A benefit of following this recommendation is that it helps ensure that EPUB Publications meet the accessibility requirements legislated in jurisdictions around the world, ensuring EPUB Creators are not locked out of potential markets.
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.
This is a very initial draft intended only as a starting point. It is inspired by the relevant section of the Publication Manifest specification. It will require more work.
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, essentially, the security and privacy issues are reliant on the features of those formats. In particular:
item
element which allows both local and remote references). This is not unlike any external reference
from an average Web site that potentially exposes users to malicious content, and EPUB Creators
should take general Web security principles into account (e.g., cross-origin resource sharing).In general, EPUB 3 tries to avoid extending the underlying technologies it builds on, but it has introduced some new features. These additions are not known to present any new privacy or security issues:
Content switching and multimedia control elements (both now deprecated) only allow hiding of content and script-less control of playback in HTML.
The expression of structural semantics in HTML and SVG only allows the annotation of elements.
The epubReadingSystem
object [EPUB-RS-33] only allows EPUB Creators to
query information about the current Reading System.
This specification contains certain features the Working Group no longer recommends for use or that are only retained for legacy support reasons. This section defines the meanings of the designations attached to these features and their support expectations.
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, the following hold true:
EPUB Creators SHOULD NOT not to use the feature in their EPUB Publications.
Reading Systems MAY support the feature.
Developers should consider the unlikelihood of encountering content with deprecated features before adding new support for them.
Validation tools SHOULD alert EPUB Creators to the presence of deprecated features when encountered in EPUB Publications.
A legacy feature is one that the Working Group has retained only for authoring content that is compatible with versions of EPUB prior to 3.0. If this specification designates a feature as legacy, the following hold true:
EPUB Creators MAY include the legacy feature for compatibility purposes.
Reading Systems MUST NOT support the legacy feature in content that conforms to this version of EPUB.
Validation tools SHOULD NOT alert EPUB Creators about the presence of legacy features in an EPUB Publication, as their inclusion is valid for backwards compatibility. Validation tools MUST alert EPUB Creators if a legacy feature does not conform to its definition or otherwise breaks a usage requirement.
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 specified in their manifest declarations. (Refer to § 2.2.4 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/svg+xml
|
-//W3C//DTD SVG 1.1//EN
|
http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd
|
Structural semantics add additional meaning about the specific structural purpose an element plays.
The epub:type
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.
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, 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
Attribute
type
http://www.idpf.org/2007/ops
Global attribute. EPUB Creators MAY specify on all elements.
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 the accessibility of EPUB
Publications, for example, they do not map to accessibility APIs used by assistive technologies. The
epub:type
attribute is only intended for publishing semantics and Reading
System enhancements. Refer to Digital Publishing
WAI-ARIA Module 1.0 [DPUB-ARIA-1.0] 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 inflected semantic MUST express a subclass of the semantic of the carrying element. In the case
of semantically neutral elements, such as the [HTML] div
and span
elements, the inflected semantic MUST NOT attach a meaning that is
already conveyed by an existing element (e.g., that a div
represents a paragraph or
section).
The default vocabulary for the epub:type
attribute is
the Structural Semantics Vocabulary. 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.
After processing [EPUB-RS-33], this property would expand to the following URL:
http://purl.org/dc/terms/modified
as the dcterms:
prefix is a reserved
prefix that maps to the URL "http://purl.org/dc/terms/
".
When an EPUB Creator omits a prefix from a property value, the expressed reference represents a term from the default vocabulary for that attribute.
An empty string does not represent a valid property value, even though it is valid to the definition above.
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.
prefix
AttributeThe 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) ; |
EPUB Creators MUST only specify the prefix
attribute on the root element 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 the 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. Validation tools 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 properties in this vocabulary are usable in the meta
element's
property
attribute.
Unless indicated otherwise in its "Extends" field, the properties defined in this section are used to
define subexpressions: in other words, a meta
element carrying a property defined in this section MUST have a refines
attribute referencing a resource or expression being
augmented.
In each property definition, the Allowed values field indicates the expected type of value (using [XMLSCHEMA-2] datatypes), the Cardinality field indicates the number of times the property MAY be attached to another property, and the Extends field identifies the properties it MAY be attached to.
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 chain these properties using the To allow Reading System 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), an identifier SHOULD be provided 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 When a scheme is not specified, Reading Systems SHOULD recognize the following collection type values:
|
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 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: |
identifier , source
|
Use of the meta-auth
property is deprecated.
For more information about this property, refer its definition in [EPUBPublications-30].
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: |
contributor , creator , 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: |
subject
|
Name: |
title-type
|
---|---|
Description: |
The When the |
Allowed value(s): |
xsd:string
|
Cardinality: |
zero or one
|
Extends: |
title
|
The properties in this vocabulary are usable in the metadata link
element's
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: |
acquire
|
---|---|
Description: | The acquire keyword is used with EPUB Previews to identify where the
full version of the EPUB Publication can be acquired. |
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="acquire" href="http://example.org/book/9781448103706"
media-type="text/html"/>
|
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
".
For more information about this property, refer its definition in [EPUBPublications-30].
Use of the mods-record
keyword is deprecated. It
is replaced by the record
keyword with the media-type
attribute value
"application/mods+xml
".
For more information about this property, refer its definition in [EPUBPublications-30].
Use of the onix-record
keyword is deprecated. It
is replaced by the record
keyword with the properties attribute value onix
.
For more information about this property, refer its definition in [EPUBPublications-30].
Name: |
record
|
---|---|
Description: |
Indicates that the referenced resource is a metadata record. The media type of the record is 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 is 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. Identification of XML signatures will be addressed in a
future version of EPUB.
For more information about this property, refer its definition in [EPUBPublications-30].
Use of the xmp-record
keyword is deprecated. It
is replaced by the record
keyword with the properties attribute value xmp
.
For more information about this property, refer its definition in [EPUBPublications-30].
The following values can be used in the link
element's
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"/>
|
Name: |
xmp
|
---|---|
Description: | The xmp property indicates the referenced resource is an XMP record
[XMP]. |
Example: |
<link rel="record" href="pub/meta/nor-wood-xmp.xml"
media-type="application/xml" properties="xmp"/>
|
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 general-purpose 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.
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.
rendition:flow
PropertyThe 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).
The following values are defined for use with the rendition:flow
property:
Dynamically paginate all overflow content.
Render all 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 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.
The rendition:flow
property MUST NOT be declared more than once.
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.
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.
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.
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 itemref
elements to override the
global value for the given spine item:
Only one of these overrides is allowed on any given spine item.
rendition:align-x-center
PropertyThe rendition:align-x-center
property specifies that the given spine item should
be centered horizontally in the viewport or spread.
The property cannot be set globally for all EPUB Content Documents. It is only available as a spine
override for individual EPUB Content Documents via the itemref
element's 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.
The following properties belong to the Package Rendering Vocabulary. Refer to their respective definitions in § 5. Fixed Layouts for the details of their use.
Properties | Defined in |
---|---|
|
§ 5.2.1 Layout |
|
§ 5.2.2 Orientation |
|
§ 5.2.3 Synthetic Spreads |
|
§ 5.2.4 Spread Placement |
|
§ 5.2.5 Viewport Dimensions (Deprecated) |
The properties in this vocabulary are usable in the manifest item
element's
properties
attribute.
The Applies to field indicates which Publication Resource type(s) the given property MAY be specified on, the Cardinality field indicates the number of times the property MUST appear within the Package Document scope, and the Usage field indicates usage conditions.
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 Publication. |
Applies to: | All raster and vector image types |
Cardinality: |
Zero or one
|
Usage: | Optional. |
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
|
Usage: | MUST be set if and only if the criterion specified in the description is met. |
Name: |
remote-resources
|
---|---|
Description: |
The Refer to § 2.2.2 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
|
Usage: | MUST be set if and only if the criterion specified in the description is met. |
Name: |
scripted
|
---|---|
Description: | The scripted property indicates that the described Publication Resource is
a Scripted Content Document (i.e., contains scripted content and/or HTML form
elements). |
Applies to: | EPUB Content Documents |
Cardinality: |
Zero or more
|
Usage: | MUST be set if and only if the criterion specified in the description is met. |
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
|
Usage: | MUST be set if and only if the criterion specified in the description is met. |
Name: |
switch
|
---|---|
Description: |
The |
Applies to: | XHTML Content Documents. |
Cardinality: |
Zero or more
|
Usage: | MUST be set if and only if the criterion specified in the description is met. |
The mathml
, remote-resources
, scripted
and switch
properties MUST be specified whenever the resource referenced by an item
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.
The properties in this vocabulary are usable in the spine itemref
element's
properties
attribute.
The prefix URL for referencing these properties is
http://idpf.org/epub/vocab/package/itemref/#
.
Name: |
page-spread-left
|
---|---|
Description: | The page-spread-left property indicates that the first page of the
associated item element's EPUB Content Document represents the
left-hand side of a two-page spread. |
Name: |
page-spread-right
|
---|---|
Description: | The page-spread-right property indicates that the first page of the
associated item element's EPUB Content Document
represents the right-hand side of a two-page spread. |
The properties in this vocabulary are usable in the meta
element's
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: | Author-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. 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. |
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>
|
While the EPUB Structural Semantics vocabulary is generally host language agnostic, it has been constructed primarily to enable semantic inflection of elements in the HTML vocabulary.
The HTML usage context fields indicate contexts in HTML documents where the given property is considered relevant. EPUB Creators may use the properties on HTML markup elements not specifically listed, but must ensure that the semantics they express represent a subset of the carrying element's semantics and do not attach an existing element's meaning to a semantically neutral element.
The DPUB-ARIA role fields indicate the [DPUB-ARIA-1.0] roles that can alternatively be used
with the [HTML] role
attribute to improve accessibility. These roles may have more
restrictive usage contexts, however, so may not be valid wherever the epub:type
attribute is used. Refer to [HTML-ARIA] for more information about where the roles are
allowed.
When processing HTML documents, Reading Systems may ignore such non-compliant properties, unless their usage context is explicitly overridden or extended by the host specification.
The Usage Details sections identify IDPF specifications that define or utilize the specified properties.
A section that introduces the work, often consisting of a marketing image, the title, author, and publisher, and select quotes and reviews.
DPUB-ARIA role: doc-cover (only allowed on cover image tag)
Preliminary material to the main content of a publication, such as tables of contents, dedications, etc.
The main content of a publication.
Ancillary material occurring after the main content of a publication, such as indices, appendices, etc.
A component of a collection.
A major structural division in a work that contains a set of related sections dealing with a particular subject, narrative arc, or similar encapsulated theme.
DPUB-ARIA role: doc-part
A major thematic section of content in a work.
DPUB-ARIA role: doc-chapter
A major sub-division of a chapter.
A major structural division that may also appear as a substructure of a part (esp. in legislation).
Sections and components that typically occur in the publication bodymatter.
A short summary of the principle ideas, concepts, and conclusions of the work, or of a section or excerpt within it.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-abstract
An introductory section that precedes the work, typically not written by the author of the work.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-foreword
An introductory section that precedes the work, typically written by the author of the work.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-preface
An introductory section that sets the background to a work, typically part of the narrative.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-prologue
A preliminary section that typically introduces the scope or nature of the work.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-introduction
A section in the beginning of the work, typically containing introductory and/or explanatory prose regarding the scope or nature of the work's content
HTML usage context: section, grouping content
A concluding section or statement that summarizes the work or wraps up the narrative.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-conclusion
A concluding section of narrative that wraps up or comments on the actions and events of the work, typically from a future perspective.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-epilogue
A closing statement from the author or a person of importance, typically providing insight into how the content came to be written, its significance, or related events that have transpired since its timeline.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-afterword
A quotation set at the start of the work or a section that establishes the theme or sets the mood.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-epigraph
A section of supplemental information located after the primary content that informs the content but is not central to it.
HTML usage context: sectioning content
DPUB-ARIA role: doc-appendix
A short section of production notes particular to the edition (e.g., describing the typeface used), often located at the end of a work.
HTML usage context: sectioning content, grouping content
DPUB-ARIA role: doc-colophon
A collection of credits.
HTML usage context: sectioning content, grouping content
DPUB-ARIA role: doc-credits
A collection of keywords.
HTML usage context: sectioning content, grouping content
A navigational aid that provides a detailed list of links to key subjects, names and other important topics covered in the work.
HTML usage context: sectioning content, body
Usage details: EPUB Indexes – index property
DPUB-ARIA role: doc-index
Narrative or other content to assist users in using the index.
Required parent context: index
HTML usage context: sectioning content, header
Usage details: EPUB Indexes – index-headnotes property
List of symbols, abbreviations or special formatting used in the index, and their meanings.
Required parent context: index-headnotes
HTML usage context: sectioning content, dl
Usage details: EPUB Indexes – index-legend property
Collection of consecutive main entries that share a common characteristic, for example the starting letter of the main entries.
Required parent context: index
HTML usage context: sectioning content
Usage details: EPUB Indexes – index-group property
Collection of consecutive main entries or subentries.
Required parent context: index-entry , index-group, and index
HTML usage context: ul; this property is implied when the ul has an ancestor of index except within index-headnotes
Usage details: EPUB Indexes – index-entry-list property
One term with any attendant subentries, locators, cross references, and/or editorial note.
Required parent context: index-entry-list
HTML usage context: li; this property is implied when parent ul is of type index-entry-list (implicit or explicit)
Usage details: EPUB Indexes – index-entry property
Word, phrase, string, glyph, or image representing the indexable content.
Required parent context: index-xref-related , index-entry and index-xref-preferred
HTML usage context: phrasing content; typically span
Usage details: EPUB Indexes – index-term property
Editorial note pertaining to a single entry.
Required parent context: index-entry
HTML usage context: flow content
Usage details: EPUB Indexes – index-editor-note property
A reference to an occurrence of the indexed content in the publication.
Required parent context: index-entry , index-locator-list , and index-locator-range
HTML usage context: a; this property is implied when parent context is index-locator-list or index-locator-range
Usage details: EPUB Indexes – index-locator property
Collection of sequential locators or locator ranges.
Required parent context: index-entry
HTML usage context: ul
Usage details: EPUB Indexes – index-locator-list property
A pair of locators that connects a term to a range of content rather than a single point.
Required parent context: index-locator-list and index-entry
HTML usage context: flow content
Usage details: EPUB Indexes – index-locator-range property
Reference from one term to one or more preferred terms or term categories in an index (analogous to "See xxx").
Required parent context: index-entry
HTML usage context: flow content
Usage details: EPUB Indexes – index-xref-preferred property
Reference from one term to one or more related terms or term categories in an index (analogous to "See also xxx").
Required parent context: index-entry
HTML usage context: flow content
Usage details: EPUB Indexes – index-xref-related property
Word, phrase, string, glyph, or image representing a category of terms in the index.
Required parent context: index-xref-related and index-xref-preferred
HTML usage context: a
Usage details: EPUB Indexes – index-term-category property
Wrapper for a list of the term categories belonging to an index.
Required parent context: index-xref-related and index-xref-preferred
HTML usage context: a
Usage details: EPUB Indexes – index-term-categories property
A brief dictionary of new, uncommon, or specialized terms used in the content.
HTML usage context: dl, sectioning content
DPUB-ARIA role: doc-glossary
A glossary term.
Required parent context: glossary
HTML usage context: The glossterm property is implied on dt elements within a dl element marked with the glossary property.
The definition of a term in a glossary.
Required parent context: glossary
HTML usage context: The glossdef property is implied on dd elements within a dl element marked with the glossary property.
A list of external references cited in the work, which may be to print or digital sources.
HTML usage context: sectioning content
DPUB-ARIA role: doc-bibliography
A single reference to an external source in a bibliography. A biblioentry typically provides more detailed information than its reference(s) in the content (e.g., full title, author(s), publisher, publication date, etc.).
Required parent context: bibliography
HTML usage context: grouping content
DPUB-ARIA role: doc-biblioentry (Deprecated)
Preliminary sections and components, typically occurring in the publication frontmatter.
The title page of the work.
HTML usage context: section, grouping content
The half title page of the work.
HTML usage context: section, grouping content
The copyright page of the work.
HTML usage context: section, grouping content
Marketing section used to list related publications.
HTML usage context: section, grouping content
A section or statement that acknowledges significant contributions by persons, organizations, governments, and other entities to the realization of the work.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-acknowledgments
Information relating to the publication or distribution of the work.
HTML usage context: section, grouping content
A formal statement authorizing the publication of the work.
HTML usage context: section, grouping content
A list of contributors to the work.
HTML usage context: section, grouping content
Acknowledgments of previously published parts of the work, illustration credits, and permission to quote from copyrighted material.
HTML usage context: section, grouping content
A set of corrections discovered after initial publication of the work, sometimes referred to as corrigenda.
HTML usage context: section, aside, grouping content
DPUB-ARIA role: doc-errata
An inscription at the front of the work, typically addressed in tribute to one or more persons close to the author.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-dedication
A record of changes made to a work.
HTML usage context: section, grouping content
A detailed analysis of a specific topic.
Inherits from: xhv:complementary
HTML usage context: sectioning content
Helpful information that clarifies some aspect of the content or assists in its comprehension.
Inherits from: xhv:complementary
HTML usage context: aside, phrasing content
Replaced by: tip
Content, both textual and graphical, that is offset in the margin.
Inherits from: xhv:complementary
HTML usage context: aside, phrasing content
Replaced by: aside
Notifies the user of consequences that might arise from an action or event. Examples include warnings, cautions and dangers.
HTML usage context: section, grouping content
DPUB-ARIA role: doc-notice
A distinctively placed or highlighted quotation from the current content designed to draw attention to a topic or highlight a key point.
Inherits from: xhv:complementary
HTML usage context: aside
DPUB-ARIA role: doc-pullquote
Secondary or supplementary content, typically formatted as an inset or box.
Inherits from: xhv:complementary
HTML usage context: aside
Replaced by: aside
Helpful information that clarifies some aspect of the content or assists in its comprehension.
Inherits from: xhv:complementary
HTML usage context: aside, phrasing content
DPUB-ARIA role: doc-tip
A warning.
HTML usage context: section, grouping content
Replaced by: notice
The title appearing on the first page of a work or immediately before the text.
Inherits from: title
HTML usage context: heading content. This property should only appear once within the document scope.
The full title of the work, either simple, in which case it is identical to title, or compound, in which case it consists of a title and a subtitle.
Inherits from: title
Same as: http://purl.org/dc/terms/title
HTML usage context: heading content. This property should only appear once within the document scope.
The title of the work as displayed on the work's cover.
Inherits from: title
HTML usage context: heading content. This property should only appear once within the document scope.
The primary name of a document component, such as a list, table, or figure.
HTML usage context: heading content, phrasing content descendants of heading content.
An explanatory or alternate title for the work, or a section or component within it.
Inherits from: title
HTML usage context: heading content, phrasing content descendants of heading content, paragraphs, divs
DPUB-ARIA role: doc-subtitle
The text label that precedes an ordinal in a component title (e.g., 'Chapter', 'Part', 'Figure', 'Table').
Inherits from: title
HTML usage context: Phrasing content descendants of heading content, li and figcaption
An ordinal specifier for a component in a sequence of components (e.g., '1', 'IV', 'B-1').
Inherits from: title
HTML usage context: Phrasing content descendants of heading content, li and figcaption
A structurally insignificant heading that does not contribute to the hierarchical structure of the work.
HTML usage context: flow content, typically p, div or span
An explicit designation or description of a learning objective or a reference to an explicit learning objective.
HTML usage context: flow content, phrasing content
A collection of learning-objectives.
HTML usage context: sectioning content, grouping content
The understanding or ability a student is expected to achieve as a result of a lesson or activity.
HTML usage context: flow content
A collection of learning-outcomes.
HTML usage context: sectioning content, grouping content
A resource provided to enhance learning, or a reference to such a resource.
HTML usage context: flow content
A collection of learning-resources.
HTML usage context: sectioning content, grouping content
A formal set of expectations or requirements typically issued by a government or a standards body.
HTML usage context: sectioning content, phrasing content
A collection of learning-standards.
HTML usage context: sectioning content, grouping content
The component of a self-assessment problem that provides the answer to the question.
HTML usage context: aside, grouping content
A collection of answers.
HTML usage context: sectioning content, grouping content
A test, quiz, or other activity that helps measure a student's understanding of what is being taught.
HTML usage context: sectioning content
A collection of assessments.
HTML usage context: sectioning content
Instruction to the reader based on the result of an assessment.
HTML usage context: grouping content, phrasing content
A problem that requires the reader to input a text answer to complete a sentence, statement or similar.
HTML usage context: aside, grouping content
A problem with a free-form solution.
HTML usage context: aside, grouping content
A section of content structured as a series of questions and answers, such as an interview or list of frequently asked questions.
HTML usage context: lists or sectioning content
DPUB-ARIA role: doc-qna
A problem that requires the reader to match the contents of one list with the corresponding items in another list.
HTML usage context: aside, grouping content
A problem with a set of potential answers to choose from ‒ some, all, or none of which may be correct.
HTML usage context: aside, grouping content
A review exercise or sample.
See also: practices
HTML usage context: aside, grouping content
The component of a self-assessment problem that identifies the question to be solved.
HTML usage context: grouping content
A collection of practices.
HTML usage context: sectioning content
A problem with either a true or false answer.
HTML usage context: aside, grouping content
An individual frame, or drawing.
HTML usage context: li
Usage details: EPUB Region-Based Navigation
A group of panels (e.g., a strip).
HTML usage context: li
Usage details: EPUB Region-Based Navigation
An area in a comic panel that contains the words, spoken or thought, of a character.
HTML usage context: li
Usage details: EPUB Region-Based Navigation
An area of text in a comic panel. Used to represent titles, narrative text, character dialogue (inside a balloon or not) and similar.
HTML usage context: li
Usage details: EPUB Region-Based Navigation
An area of text in a comic panel that represents a sound.
HTML usage context: li
Usage details: EPUB Region-Based Navigation
Explanatory information about passages in the work.
Inherits from: xhv:complementary
HTML usage context: aside, phrasing content
Replaced by: Open Annotation in EPUB
A note. This property does not carry spatial positioning semantics, as do the footnote and endnote properties. It can be used to identify footnotes, endnotes, marginal notes, inline notes, and similar when legacy naming conventions are not desired.
HTML usage context: On the aside element when identifying a single note, or on descendants of sectioning content when identifying individual notes in a group (refer to footnotes and endnotes).
Ancillary information, such as a citation or commentary, that provides additional context to a referenced passage of text.
See also: footnotes
HTML usage context: On the aside element when identifying a single footnote, or on descendants of sectioning content when identifying individual footnotes in a group (refer to footnotes and endnotes).
DPUB-ARIA role: doc-footnote
One of a collection of notes that occur at the end of a work, or a section within it, that provides additional context to a referenced passage of text.
See also: endnotes
HTML usage context: On the aside element when identifying a single endnote, or on descendants of sectioning content when identifying individual endnotes in a group (refer to footnotes and endnotes).
DPUB-ARIA role: doc-endnote (Deprecated)
A note appearing in the rear (backmatter) of the work, or at the end of a section.
See also: rearnotes
HTML usage context: On the aside element when identifying a single rearnote, or on descendants of sectioning content when identifying individual rearnotes in a group (refer to footnotes and rearnotes).
Replaced by: endnote
A collection of footnotes.
See also: footnote
HTML usage context: sectioning content
A collection of notes at the end of a work or a section within it.
See also: endnote
HTML usage context: sectioning content
DPUB-ARIA role: doc-endnotes
A collection of notes appearing at the rear (backmatter) of the work, or at the end of a section.
See also: rearnote
HTML usage context: sectioning content
Replaced by: endnotes
A reference to an annotation.
Inherits from: xhv:link
See also: annotation
HTML usage context: a
Replaced by: Open Annotation in EPUB
A reference to a bibliography entry.
Inherits from: xhv:link
HTML usage context: a
DPUB-ARIA role: doc-biblioref
A reference to a glossary definition.
Inherits from: xhv:link
HTML usage context: a
DPUB-ARIA role: doc-glossref
A reference to a note, typically appearing as a superscripted number or symbol in the main body of text.
Inherits from: xhv:link
See also: note
HTML usage context: a
DPUB-ARIA role: doc-noteref
A link that allows the user to return to a related location in the content (e.g., from a footnote to its reference or from a glossary definition to where a term is used).
Inherits from: xhv:link
HTML usage context: a
DPUB-ARIA role: doc-backlink
Terms for describing components at the phrasing level.
An acknowledgment of the source of integrated content from third-party sources, such as photos. Typically identifies the creator, copyright, and any restrictions on reuse.
HTML usage context: phrasing content
DPUB-ARIA role: doc-credit
A key word or phrase.
HTML usage context: phrasing content
A phrase or sentence serving as an introductory summary of the containing paragraph.
HTML usage context: phrasing content
A phrase or sentence serving as a concluding summary of the containing paragraph.
HTML usage context: phrasing content
A separator denoting the position before which a break occurs between two contiguous pages in a statically paginated version of the content.
Page break locators are also commonly used to provide static markers in purely digital publications (i.e., where no statically paginated equivalent exists). These markers provide consistent navigation regardless of differences in font and screen size that can otherwise affect the dynamic pagination of the content.
EPUB Creators must ensure the name of the page break is an end user-consumable page number that identifies the page that is beginning.
HTML usage context: phrasing and flow content, where the value of the carrying elements title attribute takes precedence over element content for the purposes of representing the pagebreak value
DPUB-ARIA role: doc-pagebreak
A navigational aid that provides a list of links to the pagebreaks in the content.
HTML usage context: sectioning content
DPUB-ARIA role: doc-pagelist
A structure containing data or content laid out in tabular form.
HTML usage context: Not Allowed
Media Overlays usage context: Identifies a seq or par as an escapable or skippable table structure.
A row of data or content in a tabular structure.
HTML usage context: Not Allowed
Media Overlays usage context: Identifies a seq or par as an escapable or skippable table row.
A single cell of tabular data or content.
HTML usage context: Not Allowed
Media Overlays usage context: Identifies a seq or par as an escapable or skippable table cell.
A structure that contains an enumeration of related content items.
HTML usage context: Not Allowed
Media Overlays usage context: Identifies a seq or par as an escapable or skippable list structure.
A single item in an enumeration.
HTML usage context: Not Allowed
Media Overlays usage context: Identifies a seq or par as an escapable or skippable list item.
This appendix describes the prefixed CSS properties supported by EPUB.
This section describes the -epub-
prefixed properties for [CSS-Writing-Modes-3].
-epub-text-orientation
PropertyThis is a prefixed version of the CSS text-orientation
property.
Name: | -epub-text-orientation |
---|---|
Value: | mixed | upright | sideways | sideways-right |
Previous versions of EPUB 3 used additional values of -epub-text-orientation
. User
agents MUST interpret these values according to the following table:
Deprecated value | Value to be used |
---|---|
vertical-right |
mixed |
rotate-right |
sideways |
rotate-normal |
sideways |
-epub-writing-mode
PropertyThis is a prefixed version of the CSS writing-mode
property, with the same syntax
and behavior.
Name: | -epub-writing-mode |
---|---|
Value: | horizontal-tb | vertical-rl | vertical-lr |
-epub-text-combine-horizontal
and -epub-text-combine
PropertiesThese are prefixed versions of text-combine-upright
, although
-epub-text-combine
is deprecated. See the table below for how values of both
properties translate to unprefixed CSS.
Name: | -epub-text-combine-horizontal |
---|---|
Value: | none | all |
Name: | -epub-text-combine (deprecated) |
---|---|
Value: | none | horizontal | horizontal <number> |
The following table shows how to map from the prefixed versions to the current CSS versions.
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> |
Error |
This section describes the -epub-
prefixed properties (and one prefixed value) for
[CSS-Text-3].
-epub-hyphens
PropertyThis is a prefixed version of the hyphens
property.
Name: | -epub-hyphens |
---|---|
Value: | none | manual | auto | all |
The all
value is no longer supported in CSS.
-epub-line-break
PropertyThis is a prefixed version of the line-break
property.
Name: | -epub-line-break |
---|---|
Value: | auto | loose | normal | strict |
-epub-text-align-last
PropertyThis is a prefixed version of the text-align-last
property.
Name: | -epub-text-align-last |
---|---|
Value: | auto | start | end | left | right | center | justify |
-epub-word-break
PropertyThis is a prefixed version of the word-break
property.
Name: | -epub-word-break |
---|---|
Value: | normal | keep-all | break-all |
text-transform
PropertyThis is a prefixed value for the text-transform
property.
Name: | text-transform |
---|---|
Value: | -epub-fullwidth |
The following table describes the equivalent value in CSS.
EPUB version | CSS equivalent |
---|---|
text-transform: -epub-fullwidth |
text-transform: full-width |
This section describes the -epub-
prefixed properties for [CSS-Text-Decor-3].
-epub-text-emphasis-color
PropertyThis is a prefixed version of the text-emphasis-color
property.
Name: | -epub-text-emphasis-color |
---|---|
Value: | <color> |
-epub-text-emphasis-position
PropertyThis is a prefixed version of the text-emphasis-position
property.
Name: | -epub-text-emphasis-position |
---|---|
Value: | [ over | under ] && [ right | left ] |
-epub-text-emphasis-style
PropertyThis is a prefixed version of the text-emphasis-style
property.
Name: | -epub-text-emphasis-style |
---|---|
Value: | none | [ [ filled | open ] || [ dot | circle | double-circle | triangle | sesame ] ] | <string> |
-epub-text-underline-position
PropertyThis is a prefixed version of the text-underline-position
property. One value is no
longer supported by CSS.
Name: | -epub-text-underline-position |
---|---|
Value: | auto | [ under || [ left | right ] ] | alphabetic |
The following table describes the equivalent value in CSS.
EPUB version | CSS equivalent |
---|---|
-epub-text-underline-position: alphabetic |
text-underline-position: auto |
This section is non-normative.
A non-normative 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.
container.xml
A non-normative 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].
encryption.xml
The schema for encryption.xml
files is included in
[XMLSEC-RNGSCHEMA-20130411].
signatures.xml
The schema for signatures.xml
files is included in
[XMLSEC-RNGSCHEMA-20130411].
A non-normative schema for Media Overlays 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 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">
alert("Reading System name: " + navigator.epubReadingSystem.name);
</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 HTML file it occurs in is included in
scripted01.xhtml
via the iframe
element.
The following example demonstrates the use of the OCF format to contain a signed and encrypted EPUB Publication within an OCF ZIP Container.
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 section is non-normative.
application/oebps-package+xml
Media TypeThis appendix registers the media type application/oebps-package+xml
for the EPUB
Package Document. This registration supersedes [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.
Package Documents are UTF-8 or UTF-16 encoded XML.
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 http://www.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 that can resolve
to application/oebps-package+xml
documents.
public-epub3@w3.org
COMMON
World Wide Web Consortium (W3C)
application/epub+zip
Media TypeThis section is non-normative.
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. 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 http://www.idpf.org/doc_library/epub/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 that can resolve
to application/epub+zip
and application/oebps-package+xml
documents.
public-epub3@w3.org
COMMON
World Wide Web Consortium (W3C)
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.
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 § 3.3.1.2 CSS Requirements. See issue 1614.requiredExtensions
attribute. See issue 1087.creator
and 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 informative. 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: