Editor's Draft 26 April 2016
The complete EPUB 3.1 specification is also available for download as an EPUB Publication.
Copyright © 2010-2016 International Digital Publishing Forum™
All rights reserved. This work is protected under Title 17 of the United States Code. Reproduction and dissemination of this work with changes is prohibited except with the written permission of the International Digital Publishing Forum (IDPF).
EPUB is a registered trademark of the International Digital Publishing Forum.
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
This document is a draft produced by the EPUB Working Group under the EPUB Working Group Charter approved on 8 July 2015.
This document is not considered stable and may be updated, replaced or obsoleted at any time. Its publication as a draft does not imply endorsement by IDPF membership or the IDPF Board. The document should only be cited as a work in progress.
Feedback on this document can be provided to the EPUB Working Group's mailing list or issue tracker.
This document is governed by the IDPF Policies and Procedures.
This section is informative
This specification, EPUB Packages 3.1, defines semantics and conformance requirements for an EPUB® Package. Each Package represents one Rendition of an EPUB Publication, and is defined by a Package Document that describes the content of the Rendition and sets the requirements for how Publication Resources are associated.
This specification also defines the EPUB Navigation Document, a machine- and human-readable specialization of an EPUB Content Document that provides navigation aids such as the table of contents.
This specification is one of a family of specifications [EPUB31] that compose EPUB 3.1, an interchange and delivery format for digital publications based on XML and Web Standards. It is meant to be read and understood in concert with the other specifications that make up EPUB 3.1.
This specification supersedes EPUB Publications 3.0.1 [Publications301]. Refer to [EPUB3Changes] for more information on the differences between this specification and its predecessor.
Terms with meanings specific to EPUB 3.1 are capitalized in this document (e.g., "Author", "Reading System"). A complete list of these terms and definitions is provided in [EPUB31].
Only the first instance of a term in a section is linked to its definition.
The following typographic conventions are used in this specification:
markup
All markup (elements, attributes, properties), code (JavaScript, pseudo-code), machine-readable values (string, characters, media types) and file names are in red monospace font.
markup
Links to markup and code definitions are in underlined red monospace font.
http://www.idpf.org/
URIs are in navy blue monospace font.
Hyperlinks are underlined and blue.
Normative and informative references are enclosed in square brackets.
Terms defined in the Terminology are in capital case.
Links to term definitions have a dotted blue underline.
Normative element, attribute and property definitions are in blue boxes.
Informative markup examples are in light gray boxes.
Informative notes are in green boxes with a "Note" header.
Informative cautionary notes are in red boxes with a "Caution" header.
The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [RFC2119].
All sections of this specification are normative except where identified by the informative status label "This section is informative". The application of informative status to sections and appendices applies to all child content and subsections they may contain.
All examples in this specification are informative.
For convenience, the following prefix mappings are used in this specification.
prefix | URI |
---|---|
dcterms
|
http://purl.org/dc/terms/
|
opf
|
http://www.idpf.org/2007/opf
|
rendition
|
http://www.idpf.org/vocab/rendition/#
|
A conformant EPUB Package must meet all of the following criteria:
It must contain exactly one Package Document, which must conform to the content requirements defined in Package Document—Content Conformance.
All Publication Resources associated with the Package must be listed in the Package Document (as defined in manifest).
It must contain at least one EPUB Content Document conformant to the content requirements defined in [ContentDocs31].
It may contain zero or more CSS Style Sheets conformant to the content requirements defined in CSS Style Sheets—Content Conformance [ContentDocs31].
It may contain zero or more PLS Documents conformant to the content requirements defined in PLS Documents — Content Conformance [ContentDocs31].
It may contain zero or more Media Overlay Documents conformant to the content requirements defined in [MediaOverlays31].
It may contain zero or more Publication Resources in addition to those listed above, each of which must adhere to the requirements in Publication Resources [EPUB31].
An EPUB Reading System must meet all of the following criteria:
It must process the Package Document as defined in Package Document—Reading System Conformance, and honor all presentation logic expressed through the Package Document (e.g., the reading order, fallback chains, page progression direction and fixed layouts).
It must not use any
resources not listed in the Package Document in the processing of the Package (e.g.,
META-INF
files [OCF31] and resources specific to other
Renditions of the EPUB Publication).
This section is informative
The Package Document carries the display and structural metadata associated with an EPUB Package and represents the primary source of information about how to process and display the Rendition it represents.
The Package Document is an XML document that consists of a set of container elements, each of which houses information about a particular aspect of the Package. These containers effectively centralize metadata, detail the individual resources that compose the Package and provide reading order and other information to render the Rendition.
The following list summarizes the information found in the Package Document:
Metadata — mechanisms to include and/or reference metadata applicable to the given Rendition of the EPUB Publication.
A manifest — identifies (via IRI) and describes (via MIME media type) the set of resources that collectively compose the given Rendition.
A spine — an ordered sequence of ID references to top-level resources in the manifest from which all other resources in the set can be reached or utilized. The spine defines the default reading order of the given Rendition.
Collections — a method of encapsulating and identifying subcomponents within the Package.
Manifest fallback chains — an optional 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.
A Package Document must meet all of the following criteria:
It must meet the conformance constraints for XML documents defined in XML Conformance [EPUB31].
It must be valid to the Package Document schema, as defined in Appendix C, Package Document Schema, and conform to all content conformance constraints expressed in Package Document Definition.
The Package Document filename should use the file extension .opf
.
Package Documents have the MIME media type application/oebps-package+xml
[RFC4839].
An EPUB Reading System must meet all of the following criteria:
It must process the Package Document in conformance with all Reading System conformance constraints expressed in Package Document Definition.
It should process presentational metadata, as expressed in Publication Rendering Metadata
It must process fixed layout metadata, as expressed in Fixed-Layout Properties
For fixed layouts expressed using the rendition:layout property, it must determine the rendering dimensions as defined in Fixed Layouts [ContentDocs31].
It must ignore proprietary metadata properties that pertain to layout expressions if they conflict behaviorally with the property semantics defined in Fixed-Layout Properties.
All elements [XML] defined in this section are in the
http://www.idpf.org/2007/opf
namespace [XMLNS] unless otherwise
specified.
package
ElementThe package
element is the root container of the Package Document and encapsulates metadata and resource
information associated with an EPUB Package.
package
The package
element is the root element of the Package Document.
In this order:
metadata
[required]
manifest
[required]
spine
[required]
collection
[0 or more]
The version
attribute specifies
the EPUB specification version to which the given EPUB Package conforms. The attribute must have the value "3.1
" to indicate compliance
with this version of the specification.
The
unique-identifier
attribute takes an IDREF [XML] that identifies
the dc:identifier
element that provides the
preferred, or primary, identifier. Refer to Publication Identifiers for more
information.
The prefix
attribute provides a
declaration mechanism for prefixes not reserved by this
specification. Refer to The prefix
Attribute for more information.
metadata
ElementThe metadata
element encapsulates display and rendering meta information for the given
Rendition.
metadata
Required first child of package
.
None
In any order:
dc:identifier
[required]
dc:title
[required]
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 bibliographic information for Reading Systems to use to internally catalogue an EPUB Publication and present it to a User (e.g., in a bookshelf).
to provide access to all rendering metadata needed to control the layout and display of the Rendition's content (e.g., fixed-layout properties).
The Package Document is not designed to provide a comprehensive bibliographic record, and is not the
correct location for such discovery information about the EPUB Publication. Metadata records, both that
conform to international standards or that are designed for custom use, can instead be associated using
the link
element. This approach allows the information they
contain to be presented in their native format, avoiding the problems and loss of information 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 include the [DCMES]
title
, identifier
and language
elements together
with the [DCTERMS]
modified
property. All other [DCMES] are
optional.
The following example shows the minimal set of metadata that Authors have to include in the Package Document.
<package … unique-identifier="pub-id"> … <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> <dc:identifier id="pub-id">urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809</dc:identifier> <dc:title>Norwegian Wood</dc:title> <dc:language>en</dc:language> <meta property="dcterms:modified">2011-01-01T12:00:00Z</meta> </metadata> … </package>
The meta
element provides a generic mechanism for including
metadata properties from any vocabulary. It is typically used to include rendering metadata defined in
IDPF specifications, but may be used for any metadata purposes.
See [EPUBAccessibility] for accessibility metadata recommendations.
identifier
ElementThe [DCMES]
identifier
element contains an identifier associated with the given Rendition of the EPUB Publication, such as a UUID, DOI,
ISBN or ISSN.
dc:identifier
http://purl.org/dc/elements/1.1/
Required child of metadata
.
id
[optional]
opf:scheme
[optional]
Text
The metadata
section must include an
identifier
element that contains an unambiguous identifier for the
Rendition. This identifier must be marked as the Unique Identifier via the
package
element unique-identifier
attribute.
The following example shows the unique identifier
element for an EPUB
Publication.
<package … unique-identifier="pub-id"> <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> <dc:identifier id="pub-id"> urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809 </dc:identifier> … </metadata> </package>
The Unique Identifier may differ from Rendition to Rendition, and a Rendition may include additional identifier elements.
To differentiate different versions of the same EPUB Publication, this specification makes a distinction between the Unique Identifier for an EPUB Publication and the Release Identifier that uniquely identifies a specific version of it.
To identify a specific version of a packaged EPUB Publication, a Release Identifier can be constructed by combining the Unique Identifier with the last modified date of the Rendition. For more information on the semantics and requirements of the Release Identifier, refer to Release Identifier.
The following example shows the two components of the Release Identifier.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> <dc:identifier id="pub-id"> urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809 </dc:identifier> <meta property="dcterms:modified">2016-01-01T00:00:01Z</meta> … </metadata>
Whenever a Rendition is modified, it must include a new last modified date.
To determine whether an identifier
conforms to an established system or has
been granted by an issuing authority, Reading Systems should
attempt to parse the value of the element.
For additional precision (e.g., if the scheme cannot be determined from the value or could lead
to an ambiguous result), Authors may attach an opf:scheme
attribute to assist in Reading System
identification. This attribute names the system or authority that generated or assigned the text
contained within the identifier element. When included, the opf:scheme
value
should take precedence over value parsing the
identifier.
The following example shows how an identifier can be marked as a DOI using the
opf:scheme
attribute.
<dc:identifier opf:scheme="doi"> urn:doi:10.1016/j.iheduc.2008.03.001 </dc:identifier>
This specification does not require or endorse the use of any particular scheme for
identifiers, and imposes no restrictions or requirements on opf:scheme
identifiers.
Whether to include a set of predefined values for the opf:scheme
attribute
remains under discussion. For more information, see Issue 700.
When an EPUB Publication is derived from another publication, the identifier for that source publication may be included in the metadata, but must be represented using the DCMES source element.
This specification imposes no additional restrictions or the requirements of the identifier except that it must be at least one character in length. It is strongly recommended that the identifier be a fully qualified URI, however.
Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.
title
ElementThe [DCMES]
title
element represents an instance of a name given to the EPUB Publication.
dc:title
http://purl.org/dc/elements/1.1/
Required child of metadata
.
opf:alt-script
[optional]
dir
[optional]
opf:file-as
[optional]
id
[optional]
xml:lang
[optional]
Text
The metadata
section must include at least
one title
element containing the title for the EPUB Publication.
The following example shows a multi-part title.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf"> <dc:title opf:file-as="Fellowship of the Ring"> THE LORD OF THE RINGS, Part One: The Fellowship of the Ring </dc:title> … </metadata>
Reading Systems
must treat the first title
element in document
order as the main title of the EPUB Publication (i.e., the primary one to present to Users). This specification does not define how to process additional
title
elements.
The title may differ from Rendition to Rendition.
This specification imposes no additional restrictions or requirements on the title except that it must be at least one character in length.
Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.
language
ElementThe [DCMES]
language
element specifies the language of the content of the given Rendition.
The metadata
section must include at least
one language
element with a value conforming to [RFC5646].
The following example shows an EPUB Publication is in U.S. English.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> … <dc:language>en-US</dc:language> … </metadata>
Additional language
elements may be included
for multilingual Publications, but each element's value must
conform to [RFC5646].
Languages may differ from Rendition to Rendition.
Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.
With the exception of identifier
,
language
and title
, as defined in the previous section, all other [DCMES] elements 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.
opf:alt-script
[optional]
– only allowed on
contributor
, creator
, and
publisher
.
dir
[optional]
– only allowed on
contributor
, coverage
,
creator
, description
,
publisher
, relation
,
rights
and subject
.
opf:file-as
[optional]
– only allowed on
contributor
, creator
, and
publisher
.
id
[optional]
– allowed on any element.
opf:role
[optional]
– only allowed on
contributor
and creator
.
xml:lang
[optional]
– only allowed on
contributor
, coverage
,
creator
, description
,
publisher
, relation
,
rights
and subject
.
Text
Optional metadata may differ from Rendition to Rendition.
The value of all optional [DCMES] elements must be at least one character in length.
Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.
This specification does not modify the [DCMES] element definitions except as noted in the following sections.
contributor
ElementThe contributor
element is used to represent the name of a person,
organization, etc. that played a secondary role in the creation of the content of an EPUB
Publication.
The use of the contributor
element is identical to the use of the
creator
element in all other respects, as detailed in the next
section.
creator
ElementThe creator
element represents the name of a person, organization, etc.
responsible for the creation of the content of the Rendition.
The creator
element should contain the name
of the creator as a Reading System will present it to a User.
The following example shows how a creator name can be included to facilitate sorting and rendering.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf"> … <dc:creator id="creator" opf:file-as="Murakami, Haruki"> Haruki Murakami </dc:creator> … </metadata>
If an EPUB Publication has more than one creator, each should
be included in a separate creator
element.
When determining display priority, Reading Systems must use
the document order of creator
elements in the metadata
section,
where the first creator
element encountered is the primary creator. If a Reading
System exposes creator metadata to the User, it should include
all the creators listed in the metadata
section whenever possible (e.g., when
not constrained by display considerations).
In the following example, Lewis Carroll is the primary author as he is listed first.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> … <dc:creator id="creator01">Lewis Carroll</dc:creator> <dc:creator id="creator02">John Tenniel</dc:creator> … </metadata>
Secondary contributors should be represented using DCMES
contributor
elements.
date
ElementThe 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 Rendition
was changed), which must be included using the [DCTERMS]
modified property.
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.
The following example shows a publication date.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> … <dc:date>2000-01-01T00:00:00Z</dc:date> … </metadata>
Additional dates should be expressed using the specialized date properties available in the [DCTERMS] vocabulary, or similar.
The publication date may be common to all instances of an EPUB Publication or may change from instance to instance (e.g., if the EPUB Publication gets generated on demand).
Only one date
element is allowed.
source
ElementThe source
element identifies the related resource(s) from which this EPUB Publication is derived.
When a Rendition includes page identifiers (using the pagebreak
property from the EPUB Structural Semantics Vocabulary [StructureVocab]),
it should include a source
element that
identifies the source of the pagination.
The following example shows the ISBN identifier for an EPUB Publication together with the source ISBN identifier for the print work it was derived from.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> … <dc:identifier id="isbn-id">urn:isbn:9780101010101</dc:identifier> <dc:source id="src-id">urn:isbn:9780375704024</dc:source> … </metadata>
subject
ElementThe subject
element identifies the subject of the EPUB Publication.
In addition to the attributes listed in the general
definition, the element also takes an optional opf:authority
attribute that identifies the system or scheme the element's value is drawn from. The value of
the attribute must be an absolute IRI [RFC3987] that identifies the scheme.
If both machine- and human-readable values are required, the optional opf:term
attribute can be attached. This attribute takes a string value that represents the
machine-readable code.
type
ElementThe type
element is used to indicate that the given EPUB Publication is of a
specialized type (e.g., annotations packaged in EPUB format or a dictionary).
The IDPF maintains an informative registry of specialized EPUB Publication types for use with
this element at http://www.idpf.org/epub/vocab/package/types
.
meta
ElementThe meta
element provides a generic means of including package metadata.
meta
As child of the metadata
element. Repeatable.
opf:alt-script
[optional]
dir
[optional]
opf:file-as
[optional]
id
[optional]
property
[required]
refines
[optional]
[SUPERSEDED]
scheme
[optional]
xml:lang
[optional]
Text
Each meta
element defines a metadata expression that
establishes some aspect of the EPUB Publication. The property
attribute takes a property data type value that defines the statement being made
in the expression; the text content of the element represents the assertion. (Refer to Vocabulary Association Mechanisms for more information.)
This specification reserves a set of vocabularies
for use in the property
attribute, but terms from any vocabulary may be used so long as a prefix is declared for the
vocabulary.
The following example shows various property declarations using the reserved prefixes.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> … <meta property="dcterms:modified">2016-02-29T12:34:56Z</meta> <meta property="rendition:layout">pre-paginated</meta> <meta property="media:active-class">-epub-media-overlay-active</meta> … </metadata>
The scheme
attribute identifies the system or scheme that the
element's value is drawn from. The value of the attribute must be a
property data type that resolves to the resource that
defines the scheme. If a Reading System does not recognize the scheme
attribute value,
it should treat the value of the element as a string.
Reading Systems should ignore all meta
elements
whose property
attributes define expressions they do not recognize. A Reading System
must not fail when encountering unknown expressions.
Every meta
element must express a value that is at
least one character in length after whitespace normalization.
Unless an individual property explicitly defines a different whitespace normalization algorithm,
Reading Systems must trim all leading and trailing whitespace from the
meta
element values, as defined by the XML specification [XML],
before further processing them.
link
ElementThe link
element is used to associate resources with the given Rendition of the EPUB Publication, such as metadata records.
link
As a child of metadata
.
Repeatable.
href
[required]
id
[optional]
media-type
[required]
properties
[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 must not be listed in the manifest unless they are also Publication Resources (i.e., used in the rendering of the Rendition, such as a metadata record that is serialized in an EPUB Content Document).
Linked resources that are not Publication Resources are not subject to Core Media Type requirements [EPUB31] and may be located inside or outside [EPUB31] the EPUB Container. Retrieval of Remote Resources is optional.
The required
rel
attribute takes a space-separated list of property values that establish the relationship the resource has with the Rendition.
The following example shows the link
element used to associate a local MARC XML
record.
<link rel="record" href="meta/9780000000001.xml" media-type="application/marc"/>
If a Reading System does not recognize the relationship defined in the rel
attribute,
it should ignore the referenced resource.
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 be attached with a semantic identifier.
The following example shows the properties
attribute used to identify a remote XMP
record.
<link rel="record" href="http://example.org/meta/12389347?format=xmp" media-type="application/xml" properties="xmp"/>
The list of relationships and properties recognized by this specification is defined in the EPUB Metadata Link Vocabulary.
Authors may add relationships and properties from other vocabularies via the metadata extensibility mechanism defined in this specification. Authors may also create new values by defining their own prefixes. Refer to Vocabulary Association Mechanisms for more information.
The following example shows the link
element used to associate an informational
web page. Note that as foaf is not a predefined prefix, it has to be declared in the
prefix attribute.
<package … prefix="foaf: http://xmlns.com/foaf/spec/"> <metadata> … <link rel="foaf:homepage" href="http://example.org/book-info/12389347" /> … </metadata> … </package>
In the case of linked metadata
records, the document order of link
elements in the Package Document defines
the Author's preferred precedence for their use (i.e., metadata in the first record encountered has the
highest precedence).
The following example shows that a remotely-hosted record that has higher precedence than a local one.
<metadata> … <link rel="record" href="http://example.org/onix/12389347" media-type="application/xml" properties="onix" /> <link rel="record" href="meta/meta.jsonld" media-type="application/ld+json" /> … </metadata>
If metadata records are hosted outside the container, the Author must ensure that they can be retrieved as defined in Appendix A, Metadata HTTP Protocol. Reading Systems must follow the protocol defined in the appendix when retrieving records.
When the link
element references a metadata record format that is recognized and
retrievable by a Reading System, precedence must be given to the
metadata defined in that record (i.e., metadata in the Package Document has the lowest priority). If a
Reading System recognizes more than one format, it must give precedence
to them based on the document order of link
elements, as defined above.
Due to the variety of metadata record formats and serializations that can be linked to an EPUB Publication, and the complexity of comparing metadata properties between them, this specification does not require Reading Systems to process more than one record.
Reading Systems must ignore any instructions contained in linked resources related to the layout and rendering of the EPUB Publication.
manifest
ElementThe manifest
element provides an exhaustive list of the Publication Resources
that constitute the given Rendition, each
represented by an item
element.
This specification supports internationalized resource naming, so elements and attributes that reference Publication Resources accept IRIs as their value. For compatibility with older Reading Systems that only accept URIs, resource names should be restricted to the ASCII character set.
item
ElementThe item
element represents a Publication Resource.
item
As a child of manifest
.
Repeatable.
duration
[conditionally required]
fallback
[conditionally required]
href
[required]
id
[required]
media-overlay
[optional]
media-type
[required]
properties
[optional]
Empty
Each item
element in the manifest
identifies a Publication Resource by the IRI
[RFC3987] provided in its href
attribute. The IRI may be absolute or relative. In the case of relative IRIs, Reading Systems
must use the IRI of the Package Document as the base when resolving
these to absolute IRIs. The resulting absolute IRI must be unique
within the manifest
scope.
All Publication Resources must be referenced from the
manifest
, regardless of whether they are included in the EPUB Container or made available remotely. Refer to Publication Resource Locations [EPUB31] for media type-specific
requirements regarding resource locations.
Note that the manifest
is not self-referencing: it must
not include an item
element that refers to the Package Document
itself.
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. Core Media Type Resources
must use the media type designated in EPUB Core Media Types [EPUB31].
The fallback
attribute takes an IDREF [XML] that identifies the fallback for a non-Core Media Type. All Foreign
Resources
must provide a fallback, as defined in Manifest Fallbacks.
All Publication Resources must
declare all applicable descriptive metadata properties defined in Manifest
item
Properties
[PackageVocab] via the properties
attribute. Exactly one
item
must be declared as the EPUB Navigation Document using the nav
property.
Reading Systems must ignore all descriptive metadata properties that they do not recognize.
The media-overlay
attribute takes an IDREF [XML] that identifies the Media Overlay Document for the resource described by this
item
. Refer to Packaging [MediaOverlays31] for more information.
The duration
attribute takes a [SMIL]
clock value that provides the
total duration of the audio media referenced from a Media Overlay Document or, in the case of timed
media, the total duration of the referenced media file. Refer to Package Metadata [MediaOverlays31] for more information.
The order of item
elements in the manifest
is not significant.
The presentation sequence of content documents is provided in the spine
.
The following example shows a manifest
that only contains Core Media Type
Resources.
<manifest> <item id="nav" href="nav.xhtml" properties="nav" media-type="application/xhtml+xml"/> <item id="intro" href="intro.xhtml" media-type="application/xhtml+xml"/> <item id="c1" href="chap1.xhtml" media-type="application/xhtml+xml"/> <item id="c1-answerkey" href="chap1-answerkey.xhtml" media-type="application/xhtml+xml"/> <item id="c2" href="chap2.xhtml" media-type="application/xhtml+xml"/> <item id="c2-answerkey" href="chap2-answerkey.xhtml" media-type="application/xhtml+xml"/> <item id="c3" href="chap3.xhtml" media-type="application/xhtml+xml"/> <item id="c3-answerkey" href="chap3-answerkey.xhtml" media-type="application/xhtml+xml"/> <item id="notes" href="notes.xhtml" media-type="application/xhtml+xml"/> <item id="cover" href="./images/cover.svg" properties="cover-image" media-type="image/svg+xml"/> <item id="f1" href="./images/fig1.jpg" media-type="image/jpeg"/> <item id="f2" href="./images/fig2.jpg" media-type="image/jpeg"/> <item id="css" href="./style/book.css" media-type="text/css"/> <item id="pls" href="./speech/dict.pls" media-type="application/pls+xml"/> </manifest>
The following example shows a manifest
that references two Foreign Resources, and
therefore uses the fallback chain mechanism
to supply content alternatives. The fallback chain terminates with a Core Media Type.
<manifest> <item id="item1" href="chap1_docbook.xml" media-type="application/docbook+xml" fallback="fall1"/> <item id="fall1" href="chap1.xml" media-type="application/z3998-auth+xml" fallback="fall2" /> <item id="fall2" href="chap1.xhtml" media-type="application/xhtml+xml"/> … </manifest>
Refer also to the Manifest item
properties examples for use of the properties
attribute.
spine
ElementThe spine
element defines the default reading order of the given Rendition of the EPUB Publication content by defining an ordered list of manifest item
references.
Reading Systems must provide a means of rendering the Rendition in
the order defined in the spine
, which includes: 1) recognizing the first primary
itemref
as the beginning of the default reading order; and, 2) rendering successive
primary items in the order given in the spine
.
All Publication Resources that are hyperlinked to from Publication Resources in the
spine
must themselves be listed in the spine
, where
hyperlinking is defined to be any linking mechanism that requires the User to navigate away from the current resource. Common
hyperlinking mechanisms include the href
attribute of the [HTML5]
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., all Publication
Resources hyperlinked from hyperlinked Publication Resources also have to be listed, and so on.).
All Publication Resources hyperlinked to from the EPUB Navigation Document also must be listed in the spine
, regardless of whether the Navigation
Document is itself listed the spine
.
Embedded Publication Resources (e.g., via the [HTML5]
iframe
element) do not have to 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 the default
value
is specified, the Author is expressing no preference and the Reading System can chose the rendering
direction. The default
value must be assumed when the
attribute is not specified.
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
may also provide mechanisms to override the default direction
(e.g., buttons or settings that allow the application of alternate style sheets).
Reading Systems must ignore the page progression direction defined in
pre-paginated
XHTML Content
Documents. The page-progression-direction
attribute defines the flow direction from one
fixed-layout page to the next.
itemref
ElementThe child itemref
elements of the spine
represent a sequential list
of Publication Resources (typically
EPUB Content
Documents). The order of the itemref
elements defines the default reading
order of the given Rendition of the EPUB Publication.
itemref
As a child of spine
.
Repeatable.
id
[optional]
idref
[required]
linear
[optional]
properties
[optional]
Empty
Each itemref
element must reference via an IDREF [XML] a unique item
in the manifest via its itemref
attribute.
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 the EPUB Navigation Document
is required in EPUB Publications, it is optional to include
it in the spine
.
The future of the linear
attribute in EPUB 3.1 is still uncertain. The use of the
attribute could be clarified in a future draft to better differentiate the presentation requirements
of linear and non-linear content (e.g., whether to hide non-linear content by default, or require an
option for the user to toggle), or the attribute could be removed entirely. See issue 632.
The linear
attribute indicates whether the referenced
item
contains content that contributes to the primary reading order and has to be
read sequentially ("yes
") or auxiliary content that enhances or augments the
primary content and can be accessed 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 needs to access as part of the default
read-through from supplementary content which might, for example, be presented in a popup window or
omitted from an aural rendering. Note that this specification does not require a presentation for
non-linear content; Reading Systems may handle non-linear content the
same way as linear.
Each Rendition must include at least one itemref
whose linear
attribute value is either explicitly or implicitly set to "yes
". An itemref
that omits the linear
attribute is assumed to have the value "yes
".
Authors must provide a means of accessing all non-linear content (e.g., hyperlinks in the content or from the EPUB Navigation Document).
All applicable descriptive metadata properties, such as those
defined in the Spine itemref
Properties
[PackageVocab], should be declared via the
properties
attribute.
Reading Systems must ignore all metadata properties expressed in the
properties
attribute that they do not recognize.
The following example shows a spine
element corresponding to the manifest example above.
<spine page-progression-direction="ltr"> <itemref idref="intro"/> <itemref idref="c1"/> <itemref idref="c1-answerkey" linear="no"/> <itemref idref="c2"/> <itemref idref="c2-answerkey" linear="no"/> <itemref idref="c3"/> <itemref idref="c3-answerkey" linear="no"/> <itemref idref="notes" linear="no"/> </spine>
collection
ElementThe collection
element defines a related group of resources.
collection
Optional sixth element of package
. Repeatable.
In this order: metadata
[optional]
, ( collection
[1 or more]
or ( collection
[0 or more]
, link
[1 or more]
))
The collection
element allows resources to be assembled into logical groups for a
variety of potential uses: enabling content that has been split across multiple EPUB Content Documents to be
reassembled back into a meaningful unit (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 given Rendition.
The collection
element, as defined in this section, represents a generic framework
from which specific implementations are intended to be derived (e.g., through IDPF sub-specifications).
Such implementations must define the purpose of the
collection
element within a Rendition, as well as all requirements for its valid
production and use (specifically any requirements that differ from the general framework presented
below).
Each implementation must define a
role value that uniquely identifies all conformant collection
elements. The role of each
collection
element in the Package Document must be
identified in its role
attribute, whose value must be
one or more NMTOKENs [XSD-DATATYPES] and/or absolute IRIs [RFC3987].
The use of NMTOKEN values is reserved for IDPF-defined roles, a registry of which is maintained at http://www.idpf.org/epub/vocab/package/roles
. NMTOKEN values not defined in the registry are
not valid. No roles are defined in this section.
Third parties may define custom roles for the
collection
element, but such roles must be
identified using absolute IRIs. Custom roles must not incorporate the
string idpf.org
in the host component of their identifying IRI.
To facilitate interoperability of custom roles across Reading Systems, implementers are strongly
encouraged to document their use of the collection
element at http://www.idpf.org/epub/extensions/roles
.
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 required by default.
Package-level restrictions on the use of metadata elements may be overridden.
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 IRI value of the href
attribute may have
a fragment component to indicate that only a portion or subset of a resource is included in the
collection.
The rel
attribute is optional.
The properties
attribute also accepts manifest
item properties
[PackageVocab] without a prefix (e.g., so that a collection can declare
its own Navigation Document or cover image).
Each link
must reference a resource that is a member of the group. The order of
link
elements is not significant.
Specific implementations 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.,
specific implementations cannot introduce new elements or attributes, or re-introduce those expressly
forbidden above). Specific implementations must not define collections
in a way that overrides the requirements of the manifest
and spine
.
In the context of this specification, support for collections in Reading Systems is optional. Reading Systems must ignore
collection
elements that define unrecognized roles.
The rendering of a Rendition 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.
The following example shows the assembly of two XHTML Content Documents that represent a single unit.
<package …> … <collection role="http://example.org/roles/unit"> <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> <dc:title>Foo Bar</dc:title> </metadata> <link href="EPUB/xhtml/foo-1.xhtml"/> <link href="EPUB/xhtml/foo-2.xhtml"/> </collection> … </package>
Foreign Resources may be referenced in contexts in which an intrinsic
fallback cannot be provided (e.g., directly from spine
itemref
elements; from [HTML5]
img
, iframe
and link
elements in XHTML Content Documents; and from
@import rules in CSS Style Sheets). Manifest fallbacks must be provided in such cases.
Manifest fallbacks are provided using the The
attribute on the manifest
item
Elementitem
element that represents the 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 can be reached 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 Author's preferred fallback order.
A Reading System that does not support the Media Type of a given Publication Resource must traverse the fallback chain until it has identified at least one supported Publication Resource to be used in place of the unsupported resource. If the Reading System supports multiple Publication Resources in the fallback chain, it may select the resource to use based on specific properties of that resource, otherwise it should honor the Author'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 intrinsic fallback cannot be provided, the chain must contain at least one Core Media Type Resource.
Fallback chains must not contain any circular- or self-references to
item
elements in the chain.
Fallbacks may also be provided for Top-Level Content Documents that are EPUB Content Documents; a Reading System may choose to utilize such fallbacks in order to find the optimal version of a Content Document to render in a given context. An example of when this feature can be utilized is when providing fallbacks for scripted content [ContentDocs31].
The Author is responsible for including a
primary identifier in the Package Document
metadata that is unique to one and only one EPUB Publication. This Unique Identifier, whether chosen or assigned, must be stored in the dc:identifier
element and be referenced as the Unique
Identifier in the package
element unique-identifier
attribute.
Although not static, changes to the Unique Identifier for an EPUB Publication should be made as infrequently as possible. New identifiers should not be issued when updating metadata, fixing errata or making other minor changes to the EPUB Publication.
The Unique Identifier of an EPUB Publication typically should not change with each minor revision to the package or its contents, as Unique Identifiers are intended to have maximal persistence both for referencing and distribution purposes. Each release of an EPUB Publication normally requires that the new version be uniquely identifiable, however, which results in the contradictory need for reliable Unique Identifiers that are changeable.
To redress this problem of identifying minor modifications and releases without changing the Unique Identifier, this specification defines the semantics for a Release Identifier, or means of distinguishing and sequentially ordering EPUB Publications with the same Unique Identifier.
The Release Identifier is not an actual property in the package metadata
section, but
is a value that can be obtained from two required pieces of metadata: the Unique Identifier and the last
modification date of the Rendition. When the taken together, the combined value represents a unique
identity that can be used to distinguish any particular version of an EPUB Publication from
another.
To ensure that a Release Identifier can be constructed, each Rendition must include exactly one [DCTERMS] modified property containing its last modification date. The value of this property must be an [XSD-DATATYPES] dateTime conformant date of the form:
CCYY-MM-DDThh:mm:ssZ
The last modification date must be expressed in Coordinated Universal
Time (UTC) and must be terminated by the Z
time zone
indicator.
Although not a part of the package metadata, for referencing and other purposes all string
representations of the identifier must be constructed using the at sign
(@
) as the separator (i.e., of the form "id@
date"). Whitespace
must not be included when concatenating the strings.
The following example shows how a Unique Identifier and modification date are combined to form the Release Identifier.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"> <dc:identifier id="pub-id">urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809</dc:identifier> <meta property="dcterms:modified">2011-01-01T12:00:00Z</meta> … </metadata> results in the Package ID: urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809@2011-01-01T12:00:00Z
Note that it is possible that the separator character may occur in the Unique Identifier, as these identifiers may be any string value. The Release Identifier consequently must be split on the last instance of the at sign when decomposing it into its component parts.
The Release Identifier does not supersede the Unique Identifier, but represents the means by which different versions of the same EPUB Publication can be distinguished and identified in distribution channels and by Reading Systems. The sequential, chronological order inherent in the required format of the timestamp also places EPUB Publications in order without requiring knowledge of the exact identifier that came before.
The Release Identifier consequently allows a set of EPUB Publications to be inspected to determine if they represent the same version of the same Publication, different versions of a single EPUB Publication, or any combination of differing and similar EPUB Publications.
When an EPUB Container includes more than one Rendition of an EPUB Publication, updating the last modified date of the Default Rendition for each release — even if it has not been updated — will help ensure that the EPUB Publication does not appear to be the same version as an earlier release, as Reading Systems are only required to process the Default Rendition.
This section is informative
The property
, properties
, rel
and
scheme
attributes use the property data
type to represent terms from metadata vocabularies. Similar to a CURIE [RDFa11], the property data type represents an IRI [RFC3987] in compact form and simplifies
the authoring of metadata from standardized vocabularies.
A property value is an expression that consists of a prefix and a reference, where the prefix — whether literal or implied — is a shorthand mapping of an IRI that typically resolves to a term vocabulary. When the prefix is converted to its IRI representation and combined with the reference, the resulting IRI normally resolves to a fragment within that vocabulary that contains human- and/or machine-readable information about the term.
To assist Reading Systems in processing property values, the means of establishing the IRI a prefix maps to is required, and this specification defines three such mechanisms:
a default vocabulary — defines the mapping when a property value does not include a prefix;
a set of reserved prefixes — these mappings are predefined (i.e., all Reading Systems recognize them) and can be used without having to be declared; and
the prefix
attribute — a declarative means of
creating new prefix mappings on the root package
element.
The default vocabulary is a vocabulary that does not require a prefix to be declared in order to use its terms, and whose terms must always be unprefixed.
As the Package Document has multiple unrelated uses for metadata terms, a single default vocabulary is not defined. Instead, different default vocabularies are defined for use in attributes that accept a property data type as follows:
The Package Metadata
Vocabulary is defined to be the default vocabulary for the meta
property
, meta
scheme
, item
properties
and itemref
properties
attributes.
If a property value in any of these attributes does not include a prefix, the IRI [RFC3987] stem http://idpf.org/epub/vocab/package/#
must be used to generate the resulting IRI.
The EPUB Metadata Link
Vocabulary is defined to be the default vocabulary for the link
rel
and properties
attributes.
If a property value in these attributes does not include a prefix, the IRI [RFC3987] stem http://idpf.org/epub/vocab/package/link/#
must be used to generate the resulting IRI.
The IRIs associated with the Package Metadata Vocabulary and Metadata Link Vocabulary must not be assigned a prefix using the prefix
attribute.
This specification reserves a set of prefixes that Authors may use in package metadata. These prefixes are defined in the normative document EPUB Package Document Reserved Prefixes.
The prefixes defined in this document are maintained and updated separately of this specification and are subject to change at any time.
Reading Systems must resolve all reserved prefixes used in Package Documents using their pre-defined URIs. Reserved prefixes should not be overridden in the prefix attribute, but Reading Systems must use such local overrides when encountered.
As changes to the reserved prefixes and updates to Reading Systems are not always going happen in
synchrony, Reading Systems must not fail when encountering unrecognized
prefixes (i.e., not reserved and not declared using the prefix
attribute).
prefix
AttributeThe prefix
attribute defines additional prefix mappings not reserved by the specification.
The value of the prefix
attribute is a whitespace-separated list of one or more
prefix-to-IRI 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) ; |
The following example shows prefixes for the Friend of a Friend (foaf) and
DBPedia (dbp) vocabularies being declared using the prefix
attribute.
<package … prefix="foaf: http://xmlns.com/foaf/spec/ dbp: http://dbpedia.org/ontology/"> … </package>
To avoid conflicts, the prefix
attribute must not be
used to declare a prefix that maps to the default
vocabulary. If the prefix
attribute includes a declaration for a pre-defined prefix, Reading Systems must use the URI mapping defined in the prefix
attribute,
regardless of whether of it maps to the same URI as the pre-defined prefix.
The prefix '_' is reserved for future compatibility with RDFa [RDFa11] processing, so must not be declared.
For future compatibility with alternative serializations of the Package Document, a prefix for the
Dublin Core /elements/1.1/ namespace [DCTERMS]
must not be declared in the prefix
attribute. Authors
must use only the [DCMES] elements allowed in the Package Document.
The property data type is a compact means of expressing an IRI [RFC3987] and consists of an optional prefix separated from a reference by a colon.
property | = | [ prefix , ":" ] , reference; | |
prefix | = | ? xsd:NCName ? ; | |
reference | = | ? irelative-ref ? ; | /* as defined in [RFC3987] */ |
The property data type is derived from the CURIE data type defined in [RDFa11], and represents a subset of CURIEs.
The following example shows a property value composed of the prefix dcterms and the reference modified.
<meta property="dcterms:modified">2011-01-01T12:00:00Z</meta>
After processing, this property would expand to the following IRI:
http://purl.org/dc/terms/modified
as the dcterms: prefix is a reserved prefix that maps to the IRI http://purl.org/dc/terms/
.
When a prefix is omitted from the property value, the expressed reference represents a term from the default vocabulary.
The following example shows a property value taken from the default vocabulary.
<meta … property="role">aut</meta>
This property would expand to:
http://idpf.org/epub/vocab/package/epub-vocab-package.html#role
when the IRI for the default vocabulary is concatenated with the reference.
An empty string does not represent a valid property value, even though it is valid to the definition above.
A Reading System must use the following rules to create an IRI [RFC3987] from a property:
If the property consists only of a reference, the IRI is obtained by concatenating the IRI stem associated with the default vocabulary to the reference.
If the property consists of a prefix and reference, the IRI is obtained by concatenating the IRI stem associated with the prefix to the reference. If no matching prefix has been defined, the property is invalid and must be ignored.
The resulting IRI must be valid to [RFC3987]. Reading Systems are not required to resolve this IRI, however.
This section is informative
Not all rendering information can be expressed through the underlying technologies that EPUB is built upon. Although HTML with CSS provides powerful layout capabilities, for example, those capabilities are limited to the scope of the document being rendered.
This section defines general-purpose properties that allow Authors 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 Author optimally designed it.
When the rendition:flow property
[PackageVocab] is specified on a meta
element, it
indicates the Author's global preference for overflow content handling (i.e., for all spine
items). Authors 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).
If a Reading System supports the specified rendering, it should use that method to handle overflow content, but may provide the option for Users to override the requested rendering.
The default value auto
must be assumed by Reading Systems as the global value if no
meta
element carrying this property occurs in the metadata
section. Reading Systems may support only this default value.
If a Reading Systems supports the rendition:layout property, it must ignore the
rendition:flow property when it has been set on a spine item that also
specifies the rendition:layout value pre-paginated
.
The following values are defined for use with the rendition:flow property:
The Reading System should dynamically paginate all overflow content.
The Reading System should render all Content Documents such that overflow content is scrollable, and the EPUB Publication represented by the given Rendition should be presented as one continuous scroll from spine item to spine item (except where locally overridden).
The Reading System should render all Content Documents such that overflow content is scrollable, and each spine item should be presented as a separate scrollable document.
The Author does not have a preference for overflow handling. The Reading System may render overflow content using its default method or a User preference, whichever is applicable.
The following example demonstrates an Author's intent to have a paginated Rendition with a scrollable table of contents.
<metadata> <meta property="rendition:flow">paginated</meta> </metadata> <spine> <itemref idref="toc" properties="rendition:flow-scrolled-doc"/> <itemref idref="c01"/> </spine>
The rendition:flow-auto, rendition:flow-paginated, rendition:flow-scrolled-continuous, rendition:flow-scrolled-doc and properties [PackageVocab]
may be specified locally on spine itemref
elements, and will, in such cases, override
the global value for the given spine item.
When the rendition:align-x-center property [PackageVocab] is set on a spine item, it indicates that the rendered content should be centered horizontally within the viewport or spread, as applicable. This property does not affect the rendering of the spine item, only the placement of the resulting content box.
For reflowable content, Reading Systems that support this property must center each virtual page.
This version of this specification does not define a default rendering behavior when this property is not supported or specified. Reading Systems may render spine items by their own design.
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. Authors are encouraged to use CSS solutions when effective.
This section is informative
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 [EPUB3Overview] “content presentation should adapt to the User rather than the User having to adapt to a particular representation of content.”
But this principle doesn’t work for all types of documents. Sometimes content and design are so intertwined they cannot be separated. Any change in appearance risks changing the meaning, or losing all meaning. Fixed-Layout Documents give Authors greater control over presentation when a reflowable EPUB is not suitable for the content.
This section defines a set of metadata properties to allow declarative expression of intended rendering behaviors of Fixed-Layout Documents in the context of EPUB 3.1.
EPUB 3.1 affords multiple mechanisms for representing fixed-layout content. When fixed-layout content is necessary, the Author'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 Author's choice of mechanism.
When the rendition:layout property
[PackageVocab] is specified on a meta
element, it
indicates that the paginated or reflowable layout style applies globally for the EPUB Publication (i.e., for all spine
items).
The default value reflowable
must be assumed by EPUB Reading Systems as the
global value if no meta
element carrying this property occurs in the metadata
section.
When the rendition:layout property is set to pre-paginated
, Reading Systems must not include
space between the adjacent content slots when rendering Synthetic Spreads.
When the property is set to pre-paginated
for a spine item, its
content dimensions must be set as defined in Fixed Layouts [ContentDocs31].
Refer to rendition:viewport property for how to additionally declare the dimensions within the package metadata to facilitate Reading System optimization of the rendering.
The following values are defined for use with the rendition:layout property:
The given Rendition is not pre-paginated. Reading Systems may apply dynamic pagination when rendering.
The given Rendition is pre-paginated. Reading Systems must 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, since, as a result of intrinsic properties of such documents, dynamic style changes are highly likely to have unintended consequences. Authors should take into account 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 [UAAG10] for related information.
The following example demonstrates fully fixed-layout content, using [MediaQueries] to apply different style sheets for three different device categories.
<meta property="rendition:layout">pre-paginated</meta>
<head> <meta name="viewport" content="width=1200, height=900"/> <link rel="stylesheet" href="eink-style.css" media="(max-monochrome: 3)"/> <link rel="stylesheet" href="skinnytablet-style.css" media="((color) and (max-height:600px) and (orientation:landscape), (color) and (max-width:600px) and (orientation:portrait))"/> <link rel="stylesheet" href="fattablet-style.css" media="((color) and (min-height:601px) and (orientation:landscape), (color) and (min-width:601px) and (orientation:portrait)"/> </head>
Note that the Media Queries only affect the style sheet applied to the document. The size
of the content area set in the viewport
meta
tag is static.
The rendition:layout-pre-paginated and rendition:layout-reflowable properties [PackageVocab]
may be specified locally on spine itemref
elements, and will, in such cases, override
the global value for the given spine item.
When the rendition:orientation property
[PackageVocab] is specified on a meta
element, it
indicates that the intended orientation applies globally for the given Rendition (i.e., for all
spine items).
The default value auto
must be assumed by Reading Systems as the global value if no
meta
element carrying this property occurs in the metadata
section.
The following values are defined for use with the rendition:orientation property:
The given Rendition is intended for landscape rendering.
The given Rendition is intended for portrait rendering.
The given Rendition is not orientation constrained.
Reading Systems that support multiple orientations should
convey the intended orientation to the user, unless the given value is auto
. The means by which the intent is conveyed is implementation-specific.
The following example demonstrates fully fixed-layout content intended to be rendered without synthetic spreads, and locked to landscape orientation.
<metadata> <meta property="rendition:layout">pre-paginated</meta> <meta property="rendition:spread">none</meta> <meta property="rendition:orientation">landscape</meta> </metadata>
The rendition:orientation-landscape, rendition:orientation-portrait and rendition:orientation-auto properties [PackageVocab]
may be specified locally on spine itemref
elements, and will, in such cases, override
the global value for the given spine
item.
When the rendition:spread property is
specified on a meta
element, it indicates that the intended Synthetic Spread behavior applies
globally for the given Rendition (i.e., for all spine items).
The default value auto
must be assumed by Reading Systems as the global value if no
meta
element carrying this property occurs in the metadata
section.
The following values are defined for use with the rendition:spread property:
Reading Systems must not incorporate spine items in a Synthetic Spread.
Reading Systems should render a Synthetic Spread for spine items only when the device is in landscape orientation.
Reading Systems should render a Synthetic Spread for spine items only when the device is in portrait orientation.
Reading Systems should render a Synthetic Spread regardless of device orientation.
No explicit Synthetic Spread behavior is defined. Reading Systems may use Synthetic Spreads in specific or all device orientations as part of a display area utilization optimization process.
When Synthetic Spreads are used in the context of HTML and SVG Content Documents, the dimensions given via the viewport meta element [ContentDocs31] and viewBox attribute [ContentDocs31] 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.
The following example demonstrates fully fixed-layout content intended to be rendered using synthetic spreads in landscape orientation, and with no spreads in portrait orientation.
<metadata> <meta property="rendition:layout">pre-paginated</meta> <meta property="rendition:spread">landscape</meta> </metadata>
The following example demonstrates reflowable content with a single fixed-layout title page, where the fixed-layout page is intended for right-hand spread slot if the device renders Synthetic Spreads.
<metadata> <meta property="rendition:layout">reflowable</meta> <meta property="rendition:spread">auto</meta> </metadata> <spine> <itemref idref="titlepage" properties="page-spread-right rendition:layout-pre-paginated"/> </spine>
The rendition:spread-landscape, rendition:spread-portrait, rendition:spread-both, rendition:spread-auto and rendition:spread-none properties [PackageVocab]
may be specified locally on spine itemref
elements, and will, in such cases, override
the global value for the 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. By providing one of the page-spread-left, page-spread-right or rendition:page-spread-center properties [PackageVocab] on a
spine itemref
element, an Author may override this
automatic population behavior by forcing that document to be placed in a particular viewport.
The page-spread-left property indicates that the given spine item should be rendered in the left-hand slot in the spread, and page-spread-right that it should be rendered in the right-hand slot. The rendition:page-spread-center property indicates that the synthetic spread mode should be overridden and a single viewport rendered and positioned at the center of the screen.
The page-spread-left, 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.
The page-spread-* properties take precedence over whatever value of the [CSS2.1] page-break-before property has been set for an XHTML Content Document.
The presence of rendition:page-spread-center does not change the viewport dimensions. In particular, it does not indicate that a viewport with the size of the whole spread should be created. This is important so that the scale factor stays consistent between regular and center-spread pages.
When a reflowable spine item follows a pre-paginated one, the reflowable one should start on the next page (as defined by the page-progression-direction
) when it lacks a
page-spread-* property value. If the reflowable spine item has a
page-spread-* specification, it must be
honored (e.g., by inserting a blank page).
Similarly, when a pre-paginated spine item follows a reflowable one, the pre-paginated one should start on the next page (as defined by the
page-progression-direction
) when it lacks a page-spread-*
property value. If the pre-paginated spine item has a page-spread-*
specification, it must be honored (e.g., by inserting a blank
page).
The following example demonstrates reflowable content with a two-page fixed-layout center plate that is intended to be rendered using synthetic spreads in any device orientation.
<spine page-progression-direction="ltr"> … <itemref idref="center-plate-left" properties="rendition:spread-both page-spread-left"/> <itemref idref="center-plate-right" properties="rendition:spread-both page-spread-right"/> … </spine>
Note that the author has left spread behavior for the other (reflowable) parts of the Rendition undefined, since the global
value of rendition:spread is initialized to auto
by default.
The following example demonstrates fixed-layout content, where synthetic spreads, when used, must be disabled for a center plate.
<metadata> <meta property="rendition:layout">pre-paginated</meta> <meta property="rendition:spread">auto</meta> </metadata> <spine> <itemref idref="center-plate" properties="rendition:page-spread-center"/> </spine>
Note that the rendition:spread declaration none
expression is not needed on the center plate item, as the
rendition:page-spread-center property already specifies semantics that
dictates that synthetic spreads be disabled.
The rendition:viewport property
[PackageVocab] allows Authors to express the CSS initial containing block
(ICB) [CSS2.1] for HTML and SVG Content Documents whose rendition:layout property
[PackageVocab] has been set to pre-paginated
.
The value of the property must be of the form:
width=x, height=y
where x
and y
must be the height and width of the ICB in CSS pixels [CSS2.1], respectively. The order in which the values are expressed is not
significant.
The rendition:viewport property does not replace the required ICB expression mechanisms defined in Fixed Layouts [ContentDocs31]; the property serves as a complement to facilitate Reading System optimization of the rendering. The dimensions expressed in the content and the dimensions expressed in the package metadata must match.
With the removal of the refines
attribute, it is no longer possible to create
spine-level overrides for the global viewport declaration. The working group needs to determine
if spine overrides are used in practice, or whether the internal declaration is sufficient for
correction when needed. A new mechanism for local overrides might be introduced if determined to
be necessary. See issue
643.
Reading Systems must ignore this property when it is applied to
spine items whose rendition:layout property has not been set to pre-paginated
. Reading Systems must also
ignore this property on spine items that are not HTML or SVG Content Documents.
The following example demonstrates how to set the dimensions for all spine items, overriding only a cover.
<metadata> <meta property="rendition:layout">pre-paginated</meta> <meta property="rendition:viewport">width=1200, height=900</meta> </metadata> <spine> <itemref id="cover-ref" idref="cover"/> <itemref idref="c01"/> </spine>
The protocol defined in this section is presented as an initial draft for review. The EPUB Working Group is seeking input on its implementability. To make a comment on it, please refer to Issue #703.
The metadata distribution service defined in this appendix addresses the provision and retrieval of
remotely-hosted metadata records referenced from link
elements.
The following terminology is defined for this appendix.
A set of resource data about an EPUB Publication.
The URL [RFC3986] specified in the href
attribute of a
link element that references a Metadata Record.
A program that accepts connections in order to service HTTP requests by sending HTTP responses [RFC7230].
A Server that confirms to this specification in order to distribute Metadata Records.
A program that connects to a Metadata Server in order to retrieve Metadata Records, such as a EPUB Reading System.
A conformant Metadata Server must meet the following criteria:
It must support HTTP GET method [RFC7231].
It should be an HTTP/1.1 conformant server [RFC7230] [RFC7231] [RFC7232].
It must respond with a 406 status code [RFC7231] when the server is not able to send acceptable responses.
It must return responses with Access-Control-Allow-Origin headers [RFC7232].
It may advertise its protocol
support by providing a Link header [RFC5988] with a target IRI [RFC3987] of "http://idpf.org/metadata#Container
" and relation type
of "type
".
A conformant Metadata Client must meet the following criteria:
It may access a Metadata Record URL endpoint only when the media type specified in the given link element is acceptable.
It should set the specified media type [RFC2046] for the Accept request header [RFC7231] to retrieve a Metadata Record from the Metadata Record URL. If the URL accepts any media type, the Metadata Client may send an HTTP request with the prefered Accept type.
It should use the HTTP If-Match header and ETags [RFC7232] to check whether the Metadata Record has changed since it had been updated.
Example 1. Simple Metadata Request
GET /12345 HTTP/1.1 HOST: metadata.publisher.com Accept: application/ld+json
Example 2. Simple EPUB Metadata Response
HTTP/1.1 200 OK Content-Type: application/ld+json ETag: "123456789" Link: <http://idpf.org/metadata#Container>; rel="type" Allow: GET Content-Length: 40 { "@context": { "http://schema.org" }, "@id": "12345", "@type": "Book", "bookFormatType": "EBOOK", "author": "Foo Bar", "name": "Something2016" }
This appendix lists deprecated, superseded and obsolete [EPUB31] features of the Package Document.
refines
attributeThe meta
refines
attribute is superseded.
Authors are strongly encouraged to use the dedicated attributes opf:alt-script
, opf:file-as
, opf:scheme
and opf:role
instead.
For more information about this attribute, see its definition in [Publications301].
Inclusion of an [OPF2] NCX file is obsolete. This feature will be removed in the next major version of EPUB.
The NCX provides a measure of backwards compatibility for EPUB 2 Reading Systems, but has no function in EPUB 3. It is replaced by the EPUB Navigation Document. EPUB 3 Reading Systems must ignore the NCX.
As the NCX is not used in the rendering of an EPUB 3 Publication, it can be included in the manifest without a fallback.
toc
attributeThe spine
toc
attribute is obsolete.
This attribute allows the [OPF2] NCX to be identified.
The schema for Package Documents is available at http://www.idpf.org/epub/31/schema/package-31.nvdl.
Validation using this schema requires a processor that supports [NVDL], [RelaxNG], [ISOSchematron] and [XSD-DATATYPES].
The NVDL schema layer can be substituted by a multi-pass validation using the embedded RELAX NG and ISO Schematron schemas alone.
This 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 a Rendition of an EPUB Publication. It identifies the resources in the Rendition and provides metadata information. The Package Document and its related standards are maintained and defined by the International Digital Publishing Forum (IDPF).
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 Publications 3.0 standard 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 Publications 3.0 specification located at http://www.idpf.org/epub/30/spec/epub30-publications.html.
The EPUB Publications 3.0 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. The following list of applications is not exhaustive.
Adobe Digital Editions
Aldiko
Azardi
Apple iBooks
Barnes & Noble Nook
Calibre
Google Books
Ibis Reader
MobiPocket reader
Sony Reader
Stanza
none
.opf
TEXT
The IDPF maintains a registry of linking schemes at http://www.idpf.org/epub/linking/
. Some of these schemes define custom
fragment identifiers that resolve to application/oebps-package+xml
documents.
William McCoy, bmccoy@idpf.org
COMMON
International Digital Publishing Forum (http://www.idpf.org)
This section is informative
EPUB has been developed by the International Digital Publishing Forum in a cooperative effort, bringing together publishers, vendors, software developers, and experts in the relevant standards.
The EPUB 3.1 specifications were prepared by the International Digital Publishing Forum’s EPUB Maintenance Working Group, operating under a charter approved by the membership in July 2015, under the leadership of:
Active members of the working group included:
For more detailed acknowledgements and information about contributors to each version of EPUB, refer to Acknowledgements and Contributors [EPUB3Overview].
[CSS2.1] Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification . 7 June 2011.
[ContentDocs31] EPUB Content Documents 3.1 .
[DCTERMS] DCMI Metadata Terms .
[DateTime] Date and Time Formats . 15 September 1997.
[EPUB31] EPUB 3.1 .
[EPUBAccessibility] EPUB Accessibility .
[ISOSchematron] ISO/IEC 19757-3: Rule-based validation — Schematron .
[MARCRelators] MARC Code List for Relators.
[MediaOverlays31] EPUB Media Overlays 3.1 .
[MediaQueries] Media Queries .
[OCF31] Open Container Format 3.1 .
[OPF2] Open Packaging Format 2.0.1 .
[PackageVocab] EPUB 3.1 Package Metadata Vocabulary .
[Packages31] EPUB Packages 3.1 .
[Publications301] EPUB Publications 3.0.1 .
[RDFa11] RDFa Core 1.1 - Second Edition . Syntax and processing rules for embedding RDF through attributes. 22 August 2013.
[RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types (RFC 2046) . November 1996.
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels (RFC 2119) . March 1997.
[RFC3986] Uniform Resource Identifier (URI): Generic Syntax (RFC 3986) . January 2005.
[RFC3987] Internationalized Resource Identifiers (IRIs) (RFC 3987) . January 2005.
[RFC4839] Media Type Registrations for the Open eBook Publication Structure (OEBPS) Package File (OPF) (RFC 4839) . April 2007.
[RFC5646] Tags for Identifying Languages (RFC 5646) . September 2009.
[RFC5988] Web Linking (RFC 5988). October 2010.
[RFC7230] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing (RFC 7230). June 2014.
[RFC7231] Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content (RFC 7231). June 2014.
[RFC7232] Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests (RFC 7232). June 2014.
[RelaxNG] ISO/IEC 19757-2: Regular-grammar-based validation — RELAX NG. Second Edition . 2008-12-15.
[SMIL] SMIL Version 3.0 . 01 December 2008.
[StructureVocab] EPUB 3 Structural Semantics Vocabulary .
[UAAG10] User Agent Accessibility Guidelines 1.0 . 17 December 2002.
[Unicode] The Unicode Consortium. The Unicode Standard..
[WAI-ARIA-1.1] Accessible Rich Internet Applications (WAI-ARIA) 1.1 .
[XML] Extensible Markup Language (XML) 1.0 (Fifth Edition) . 26 November 2008.
[XMLNS] Namespaces in XML (Third Edition) . 8 December 2009.
[XSD-DATATYPES] XML Schema Part 2: Datatypes Second Edition . 28 October 2004.
[EPUB3Changes] EPUB 3.0.1 Differences from EPUB 3.0 .
[EPUB3Overview] EPUB 3.1 Overview .