The metadata Element

The metadata element encapsulates meta information for the given Rendition.

Element Name

metadata

Usage

REQUIRED first child of package.

Attributes

None

Content Model

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]

• OPF2 meta [0 or more] (legacy)

• link [0 or more]

The Package Document metadata element has two primary functions:

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

2. 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 complex metadata encoding capabilities. If more detailed information about an EPUB Publication is needed, metadata records (e.g., that conform to an international standard such as [[!ONIX]] or are created for custom purposes) can be associated using the link element. This approach allows the metadata to be processed 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 include the [[!DC11]] 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. It is typically used to include rendering metadata defined in EPUB specifications, but MAY be used for any metadata purposes.

DCMES Required Elements

DCMES Optional Elements

The meta Element

The meta element provides a generic means of including package metadata.

Element Name

meta

Usage

As child of the metadata element. Repeatable.

Attributes

• dir [optional]

• id [optional]

• property [required]

• refines [optional]

• scheme [optional]

• xml:lang [optional]

Content Model

Text

Each meta element defines a metadata expression. The property attribute takes a property data type value that defines the statement being made in the expression, and the text content of the element represents the assertion. (Refer to Vocabulary Association Mechanisms for more information.)

This specification defines two types of metadata expressions that can be defined using the meta element:

• A primary expression is one in which the expression defined in the meta element establishes some aspect of the EPUB Publication. A meta element that omits a refines attribute defines a primary expression.
• A subexpression is one in which the expression defined in the meta element enhances the meaning of the expression or resource referenced in its refines attribute. 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.

Subexpressions are not limited to refining only primary expressions and resources; they may be used to refine the meaning of other subexpressions, thereby creating chains of information.

All of the DCMES [[!DC11]] elements represent primary expressions, and permit refinement by meta element subexpressions.

This specification reserves the Meta Properties Vocabulary for use with the property attribute. Terms from other vocabularies MAY be used provided they have a prefix (refer to Reserved Prefixes for a list of prefixes that do not have to be declared).

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.

Unless an individual property explicitly defines a different white space normalization algorithm, Reading Systems MUST trim all leading and trailing white space [[!XML]] from the meta element values before further processing them.

Every meta element MUST express a value that is at least one character in length after white space normalization.

The link Element

The link element is used to associate resources with the given Rendition, such as metadata records.

Element Name

link

Usage

As a child of metadata. Repeatable.

Attributes

• href [required]

• id [optional]

• media-type [conditionally required]

• properties [optional]

• refines [optional]

• rel [required]

Content Model

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 not Publication Resources and MUST NOT be listed in the manifest. A linked resource MAY be embedded in a Publication Resource that is listed in the manifest, however, in which case it MUST be a Core Media Type Resource [[!EPUB32]] (e.g., an EPUB Content Document could contain a metadata record serialized as [[RDFA-CORE]] or [[JSON-LD]]).

Linked resources MAY be located locally or remotely, but Authors need to be aware that retrieval of Remote Resources by Reading Systems is OPTIONAL (i.e., the resource might not be 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 IRI. The attribute is REQUIRED for all Local Resources.

The REQUIRED rel attribute takes a space-separated list of property values that establish the relationship the resource has with the Rendition.

Reading System do not have to use or present linked resources, even if they recognize the relationship defined in the rel attribute.

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 list of reserved 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 also MAY create new values by defining their own prefixes. Refer to Vocabulary Association Mechanisms for more information.

In the case of a linked metadata record, Reading Systems MUST NOT skip processing the metadata expressed in the Package Document and only use the information expressed in the record. Linked records are intended to enhance the information available to Reading Systems, and the package metadata typically contains important rendering information. Reading Systems MAY compile metadata from multiple linked records; they do not have to select only one record.

When it comes to resolving discrepancies and conflicts between metadata expressed in the Package Document and in linked metadata records, Reading Systems MUST use the document order of link elements in the Package Document to establish precedence (i.e., metadata in the first linked record encountered has the highest precedence and metadata in the Package Document the lowest, regardless of whether the link elements occur before, within or after the package metadata elements).

Reading Systems MUST ignore any instructions contained in linked resources related to the layout and rendering of the EPUB Publication.

The manifest Element

The manifest element provides an exhaustive list of the Publication Resources that constitute the given Rendition, each represented by an item element.

Element name

manifest

Usage

REQUIRED second child of package, following metadata.

Attributes

id [optional]

Content Model

item [1 or more]

The item Element

The item element represents a Publication Resource.

Element Name

item

Usage

As a child of manifest. Repeatable.

Attributes

• fallback [conditionally required]

• href [required]

• id [required]

• media-overlay [optional]

• media-type [required]

• properties [optional]

Content Model

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 Local or Remote Resources. Refer to Publication Resource Locations [[!EPUB32]] 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 Supported Media Types [[!EPUB32]].

The fallback attribute takes an IDREF [[!XML]] that identifies a fallback for the Publication Resource referenced from the item element. Fallbacks MAY be provided for Core Media Type Resources (e.g., to provide a static alternative to a Scripted Content Document). Fallback requirements for Foreign Resources are defined in Manifest Fallbacks.

This specification reserves the EPUB Manifest Properties Vocabulary for use with the properties attribute. Terms from other vocabularies MAY be used provided they have a prefix (refer to Reserved Prefixes for a list of prefixes that do not have to be declared).

Authors MUST declare all applicable descriptive metadata properties for each Publication Resource in this attribute, as Reading Systems MAY optimize the rendering depending on the properties that have been set (e.g., disable a rendering process or use a fallback). Reading Systems MUST ignore all descriptive metadata properties that they do not recognize.

Exactly one item MUST be declared 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 Packaging [[!MediaOverlays32]] for more information.

Examples

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

Manifest Fallbacks

Foreign Resources MAY be referenced 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). Manifest fallbacks MUST be provided in such cases.

Manifest fallbacks are provided using the fallback attribute on the manifest item 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. If a Reading System does not support any resource in the fallback chain, it MUST alert the reader that content could not be displayed.

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. User agents MUST terminate the fallback chain at the first reference to a manifest item that has already been encountered.

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 [[!ContentDocs32]].

The 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 [[!Publications301]] for more information about this element.

The spine Element

The spine element defines an ordered list of manifest item references that represent the default reading order of the given Rendition.

Element name

spine

Usage

REQUIRED third child of package, following manifest.

Attributes

• id [optional]

• page-progression-direction [optional]

• toc [optional] (legacy)

Content Model

itemref [1 or more]

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 [[!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., 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 in the spine.

Embedded Publication Resources (e.g., via the [[!HTML]] 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 choose the rendering direction. The default value MUST be assumed when the attribute is not specified. In this case, the reading system SHOULD choose a default page-progression-direction value based on the first language element.

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.

The legacy toc attribute takes an IDREF [[!XML]] that identifies the manifest item that represents the NCX.

The itemref Element

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

Element Name

itemref

Usage

As a child of spine. Repeatable.

Attributes

• id [optional]

• idref [required]

• linear [optional]

• properties [optional]

Content Model

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.

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 reading order from supplementary content which might, for example, be presented in a popup window or omitted from an aural rendering.

When rendering an EPUB Publication, a Reading System MAY either suppress non-linear content so that it does not appear in the default reading order, or ignore the linear attribute in order to provide users access to the entire content of the EPUB Publication. This specification does not mandate which model Reading Systems have to use. A Reading System MAY also provide the option for users to toggle between the two models.

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

This specification reserves the EPUB Spine Properties Vocabulary for use with the properties attribute. Terms from any other vocabulary MAY be used provided they have a prefix (refer to Reserved Prefixes for a list of prefixes that do not have to be declared).

All applicable descriptive metadata properties defined in the Spine Properties Vocabulary SHOULD be declared.

Reading Systems MUST ignore all metadata properties expressed in the properties attribute that they do not recognize.

Examples

The collection Element

The collection element defines a related group of resources.

Element Name

collection

Usage

OPTIONAL sixth element of package. Repeatable.

Attributes

• dir [optional]

• id [optional]

• role [required]

• xml:lang [optional]

Content Model

In this order: metadata [0 or 1], ( 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 specializations are intended to be derived (e.g., through EPUB sub-specifications). Such specializations 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 specialization 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 [[!XMLSCHEMA-2]] and/or absolute IRIs [[!RFC3987]]. The use of NMTOKEN values is reserved for roles not defined in EPUB, which are maintained in the [[!RoleRegistry]]. 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.

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.

• Package-level restrictions on the use of metadata elements MAY be overridden.

• All primary metadata expressions apply to the collection.

• The refines attribute MUST NOT reference elements outside the containing collection.

• The OPF2 meta element MUST NOT be included.

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

• The refines attribute MUST NOT be attached.

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.

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.

Examples

The meta Element

The meta element [[!OPF2]] is a legacy feature that previously provided a means of including generic metadata. It is replaced in EPUB 3 by the updated meta element, which uses different attributes and requires text content.

For more information about the meta element, refer to its definition in [[!OPF2]].

The guide Element

The guide element [[!OPF2]] is a legacy feature that previously provided machine-processable navigation to key structures in an EPUB Publication. It is replaced in EPUB 3 by landmarks in the EPUB Navigation Document.

For more information about the guide element, refer to its definition in [[!OPF2]].

NCX

The NCX [[!OPF2]] is a legacy feature that previously provided the table of contents for EPUB Publications. It is replaced in EPUB 3 by the EPUB Navigation Document.

For more information about the NCX, refer to its definition in [[!OPF2]].

Syntax

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.

The property data type is derived from the CURIE data type defined in [[!RDFA-CORE]], and represents a subset of CURIEs.

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

Processing

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 do not have to resolve this IRI, however.

The rendition:flow Property

The rendition:flow property specifies the Author preference for how Reading Systems should handle content overflow.

The rendition:align-x-center Property

The rendition:align-x-center property specifies that the given spine item should be centered horizontally in the viewport or spread.

When the rendition:align-x-center property 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.

The rendition:layout Property

The rendition:layout property specifies whether the given Rendition is reflowable or pre-paginated.

The rendition:orientation Property

The rendition:orientation property specifies which orientation the Author intends the given Rendition to be rendered in.

The rendition:spread Property

The rendition:spread property specifies the intended Reading System synthetic spread behavior for the given Rendition.

The rendition:page-spread-* Properties

The rendition:viewport Property (Deprecated)

The rendition:viewport property allows Authors to express the CSS initial containing block (ICB) [[!CSS21]] 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 [[!Publications301]] for more information.

The toc nav Element

The toc nav element defines the primary navigational hierarchy of the given Rendition. It conceptually corresponds to a table of contents in a printed work (i.e., it provides navigation to the major structural sections of the publication).

The references in the toc nav element MUST be ordered such that they reflect both:

• the order of the referenced EPUB Content Documents in the spine;

• the order of the targeted elements within their respective EPUB Content Documents.

The toc nav element MUST occur exactly once in an EPUB Navigation Document.

The page-list nav Element

The page-list nav element provides navigation to positions in the content that correspond to the locations of page boundaries present in a print source being represented by the EPUB Publication.

The page-list nav element is OPTIONAL in EPUB Navigation Documents and MUST NOT occur more than once.

The page references within the page-list nav MUST be ordered so that they match both the order of the targeted EPUB Content Documents in the spine and the order of each page within its respective EPUB Content Document.

The page-list nav element SHOULD contain only a single ol descendant (i.e., no nested sublists).

The destinations of the page-list references MAY be identified in their respective EPUB Content Documents using the pagebreak term [[!EPUB-SSV]].

The landmarks nav Element

The landmarks nav element identifies fundamental structural components in the given Rendition in order to enable Reading Systems to provide the user efficient access to them.

The epub:type attribute [[!ContentDocs32]] is REQUIRED on a element descendants of the landmarks nav element. The structural semantics of each link target within the landmarks nav element is determined by the value of this attribute.

The landmarks nav MUST NOT include multiple entries with the same epub:type value that reference the same resource, or fragment thereof.

The landmarks nav element is OPTIONAL in EPUB Navigation Documents and MUST NOT occur more than once.

Other nav Elements

EPUB Navigation Documents MAY include one or more nav elements in addition to the toc, page-list and landmarks nav elements defined in the preceding sections. These additional nav elements SHOULD have an epub:type attribute to provide a machine-readable semantic, and MUST have a human-readable heading as their first child.

This specification imposes no restrictions on the semantics of any additional nav elements: they MAY be used to represent navigational semantics for any information domain, and they MAY contain link targets with homogeneous or heterogeneous semantics.