Package Metadata Vocabulary

26 April 2016

This version
http://www.idpf.org/epub/vocab/package/epub-vocab-package-20160426.html
Latest version
http://www.idpf.org/epub3/latest/package-vocab
Previous version
http://www.idpf.org/epub/vocab/package/epub-vocab-package-20160130.html
Document history

Editors

Markus Gylling, International Digital Publishing Forum (IDPF)

Matt Garrish, Invited Expert

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.

Status of this Document

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.

  1 Overview

  1.1 Purpose and Scope

This section is informative

This vocabulary, a part of EPUB® 3, defines a set of properties for describing various features of the Package Document [Packages31].

The properties in this vocabulary are usable in the various Package Document attributes that accept the property datatype [Packages31], and are grouped by the element and attribute that they can be used in.

This vocabulary is a companion to the [Packages31] specification and is intended to be read in conjunction with that document.

  1.2 Referencing

Properties without a prefix are referenceable using the base IRI http://idpf.org/epub/vocab/package/#.

Properties with the "rendition:" prefix are referenceable using the base IRI http://www.idpf.org/vocab/rendition/#.

The "rendition:" prefix is reserved for use [Packages31] and does not have to be declared in the Package Document.

  1.3 Terminology

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.

  1.4 Conformance Statements

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.

  2 Metadata meta Properties

  2.1 rendition:flow

Name: rendition:flow
Description:Specifies the Author preference for how Reading Systems should handle content overflow.
Allowed value(s):

paginated | scrolled-continuous | scrolled-doc | auto

The default value is auto

Cardinality: Zero or one
Extends:Sets the global value for the given Rendition.
Example: <meta property="rendition:flow">scrolled-doc</meta>

  2.2 rendition:layout

Name: rendition:layout
Description:Specifies whether the given Rendition is reflowable or pre-paginated.
Allowed value(s):

reflowable | pre-paginated

The default value is reflowable

Cardinality: Zero or one
Extends:Sets the global value for the given Rendition.
Example: <meta property="rendition:layout">pre-paginated</meta>

  2.3 rendition:orientation

Name: rendition:orientation
Description:Specifies which orientation the Author intends the given Rendition to be rendered in.
Allowed value(s):

landscape | portrait | auto

The default value is auto

Cardinality: Zero or one
Extends:Sets the global value for the given Rendition.
Example: <meta property="rendition:orientation">landscape</meta>

  2.4 rendition:spread

Name: rendition:spread
Description:Specifies the intended Reading System synthetic spread behavior for the given Rendition.
Allowed value(s):

none | landscape | portrait | both | auto

The default value is auto

Cardinality: Zero or one
Extends:Sets the global value for the given Rendition.
Example: <meta property="rendition:spread">both</meta>

  2.5 rendition:viewport

Name: rendition:viewport
Description:Specifies the CSS initial containing block [CSS2.1] dimensions for pre-paginated [Packages31] XHTML and SVG Content Documents.
Required value: width=x, height=y
Cardinality:

Zero or one

Extends:Sets the global value for the given Rendition.
Example: <meta property="rendition:viewport">width=1200, height=800</meta>

  3 Manifest item Properties

The following tables define properties for use in the manifest item element [Packages31] properties attribute [Packages31].

The Applies to field indicates which Publication Resource type(s) the given property may be specified on, the Cardinality field indicates the number of times the property must appear within the Package Document scope, and the Usage field indicates usage conditions.

  3.1 cover-image

Name: cover-image
Description:The cover-image property identifies the described Publication Resource as the cover image for the Publication.
Applies to:All raster and vector image types [EPUB31]
Cardinality: Zero or one
Usage:Optional.

  3.2 mathml

Name: mathml
Description:The mathml property indicates that the described Publication Resource contains one or more instances of MathML markup.
Applies to:EPUB Content Documents
Cardinality: Zero or more
Usage:Must be set if and only if the criterion specified in the description is met.

  3.3 nav

  3.4 remote-resources

Name: remote-resources
Description:

The remote-resources property indicates that the described Publication Resource contains one or more internal references to other Publication Resources that are located outside of the EPUB Container.

Refer to Publication Resource Locations [EPUB31] for more information.

Applies to:All Publication Resources with the capability of internal referencing (e.g., XHTML Content Documents, SVG Content Documents, CSS Style Sheets and Media Overlay Documents).
Cardinality: Zero or more
Usage:Must be set if and only if the criterion specified in the description is met.

  3.5 scripted

Name: scripted
Description:The scripted property indicates that the described Publication Resource is a Scripted Content Document (i.e., contains scripted content and/or elements from HTML5 forms).
Applies to:EPUB Content Documents
Cardinality: Zero or more
Usage:Must be set if and only if the criterion specified in the description is met.

  3.6 svg

Name: svg
Description:

The svg property indicates that the described Publication Resource embeds one or more instances of SVG markup.

This property must be set when SVG markup is included directly in the resource and may be set when the SVG is referenced from the resource (e.g., from an [HTML5] img, object or iframe element).

Applies to:XHTML Content Documents; the value is implied for SVG Content Documents.
Cardinality: Zero or more
Usage:Must be set if and only if the criterion specified in the description is met.

  3.7 Usage

The mathml, remote-resources, scripted and switch properties must be specified whenever the resource referenced by an item matches their respective definitions. These properties do not apply recursively to content included into a resource (e.g., via the HTML5 iframe element). For example, if a non-scripted XHTML Content Document embeds a scripted Content Document, only the embedded document's manifest item properties attribute will have the scripted value.

  3.8 Examples

The following example shows a manifest item element [Packages31] that represents the EPUB Navigation Document.

<item properties="nav" id="c1" href="c1.xhtml" media-type="application/xhtml+xml" />

The following example shows a manifest item element that represents the cover image.

<item properties="cover-image" id="ci" href="cover.svg" media-type="image/svg+xml" />

The following example shows a manifest item element representing a Scripted Content Document that also contains embedded MathML.

<item properties="scripted mathml" id="c2" href="c2.xhtml" media-type="application/xhtml+xml" />

  4 Spine itemref Properties

The following tables define properties for use in the itemref element [Packages31] properties attribute [Packages31].

The Cardinality field indicates the number of times the property must appear within the Package Document scope, and the Usage field indicates usage conditions.

  4.1 rendition:align-x-center

Name: rendition:align-x-center
Description: Specifies that the given spine item should be centered horizontally in the viewport or spread.
Cardinality: Zero or more
Usage:Optional.

  4.2 rendition:flow-auto

Name: rendition:flow-auto
Description: Indicates no preference for overflow content handling by the Author.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:flow-paginated, rendition:flow-scrolled-continuous or rendition:flow-scrolled-doc properties.

  4.3 rendition:flow-paginated

Name: rendition:flow-paginated
Description: Indicates the Author preference is to dynamically paginate content overflow.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:flow-auto, rendition:flow-scrolled-continuous or rendition:flow-scrolled properties.

  4.4 rendition:flow-continuous

Name: rendition:flow-scrolled-continuous
Description:

Indicates the Author preference is to provide a scrolled view for overflow content, and that consecutive spine items with this property are to be rendered as a continuous scroll.

The scroll direction is defined relative to the block flow direction [CSS3WritingModes] of the root element of the XHTML Content Document referenced by the itemref element [Packages31]. The scroll direction is vertical if the block flow direction is downward (top-to-bottom). It is horizontal if the block flow direction of the root element is rightward (left-to-right) or leftward (right-to-left).

Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:flow-auto, rendition:flow-scrolled-doc or rendition:flow-paginated properties.

  4.5 rendition:flow-scrolled-doc

Name: rendition:flow-scrolled-doc
Description: Indicates the Author preference is to provide a scrolled view for overflow content, and each spine item with this property is to be rendered as separate scrollable document.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:flow-auto, rendition:flow-scrolled-continuous or rendition:flow-paginated properties.

  4.6 rendition:layout-pre-paginated

Name: rendition:layout-pre-paginated
Description: Specifies that the given spine item is pre-paginated.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:layout-reflowable property.

  4.7 rendition:layout-reflowable

Name: rendition:layout-reflowable
Description: Specifies that the given spine item is reflowable.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:layout-pre-paginated property.

  4.8 rendition:orientation-auto

Name: rendition:orientation-auto
Description: Specifies that the Reading System can determine the orientation to rendered the spine item in.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:orientation-landscape or rendition:orientation-portrait property.

  4.9 rendition:orientation-landscape

Name: rendition:orientation-landscape
Description: Specifies that the given spine item is to be rendered in landscape orientation.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:orientation-portrait or rendition:orientation-auto property.

  4.10 rendition:orientation-portrait

Name: rendition:orientation-portrait
Description: Specifies that the given spine item is to be rendered in portrait orientation.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:orientation-landscape or rendition:orientation-auto property.

  4.11 rendition:page-spread-center

Name: rendition:page-spread-center
Description: Specifies the forced placement of a Content Document in a Synthetic Spread
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the page-spread-right or page-spread-left properties.

  4.12 page-spread-left

Name: page-spread-left
Description:The page-spread-left property indicates that the first page of the associated item element's EPUB Content Document represents the left-hand side of a two-page spread.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the page-spread-right or rendition:page-spread-center properties.

  4.13 page-spread-right

Name: page-spread-right
Description:The page-spread-right property indicates that the first page of the associated item element's EPUB Content Document represents the right-hand side of a two-page spread.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the page-spread-left or rendition:page-spread-center properties.

  4.14 rendition:spread-auto

Name: rendition:spread-auto
Description: Specifies the Reading System can determine when to render a synthetic spread for the spine item.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:spread-portrait, rendition:spread-landscape, rendition:spread-both or rendition:spread-none property.

  4.15 rendition:spread-both

Name: rendition:spread-both
Description: Specifies the Reading System should render a synthetic spread for the spine item in both portrait and landscape orientations.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:spread-portrait, rendition:spread-landscape, rendition:spread-auto or rendition:spread-none property.

  4.16 rendition:spread-landscape

Name: rendition:spread-landscape
Description: Specifies the Reading System should render a synthetic spread for the spine item only when in landscape orientation.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:spread-portrait, rendition:spread-both, rendition:spread-auto or rendition:spread-none property.

  4.17 rendition:spread-none

Name: rendition:spread-none
Description: Specifies the Reading System should not render a synthetic spread for the spine item.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:spread-portrait, rendition:spread-landscape, rendition:spread-both or rendition:spread-auto property.

  4.18 rendition:spread-portrait

Name: rendition:spread-portrait
Description: Specifies the Reading System should render a synthetic spread for the spine item only when in portrait orientation.
Cardinality: Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the rendition:spread-landscape, rendition:spread-both, rendition:spread-auto or rendition:spread-none property.

  4.19 Examples

The following example shows how a two-page spread of a map might be indicated in the spine.

<spine>
	<itemref idref="title"/>
	<itemref idref="ps-1-l" properties="page-spread-left"/>
	<itemref idref="ps-1-r" properties="page-spread-right"/>
	<itemref idref="toc"/>
	…
</spine>

  References

Normative References

[CSS3WritingModes] CSS Writing Modes Module Level 3 . Elika J. Etemad, et al.

[EPUB31] EPUB 3.1 .

[Packages31] EPUB Packages 3.1 .