File Requirements

Last updated: 2024-06-24

Book submissions to O’Reilly Learning require three files: a cover, an ePub, and an XML metadata file.

Why ePub?

The ePub format creates a superior experience for the growing number of subscribers accessing O’Reilly Learning on mobile devices. Text and images in ePub sources resize and reflow to fit changing screen sizes.

Requirements

Before uploading to the O’Reilly Learning Platform, ePub sources must successfully validate with EPUBCheck 5.1.0. ePub sources must be reflowable; fixed-layout ePubs will not render properly and will be unusable. During ingestion the ePub and CSS will be used to generate HTML views and the Table of Contents (ToC) for browsers and mobile devices.

Important
 Attempts to use CSS to duplicate functions already present in HTML (e.g. <p>, <span> and <div>) may not render properly and should not be used in place of built-in HTML functions.

Additionally:

  • There can be no missing or empty navPoint IDs.

  • All navPoint IDs must be unique within a given ePub.

  • All ToCs, including a toc.html in the ePub, must reference content in the order it appears in the book or ePub.

The ToC should include, at minimum, chapter titles. The structure should be hierarchical, i.e., section titles should be nested within chapter titles. Version 3.0 of the ePub specs note that the toc.ncx file has been superseded by the "ePub Navigation Document"; however, ePub 3.0 sources must contain a toc.ncx for backward compatibility with ePub 2.0 reading systems. The ePub 3.0 specs can be found here.

Accessibility Guide

Our membership is diverse and our goal is to support learning needs and preferences across a wide variety of content formats and devices. We strongly recommend that our partner publishers strive for AA-level conformance per the W3C’s Web Content Accessibility Guidelines (WCAG).

Before uploading your content, please review this page for an overview of the accessibility features of the O’Reilly Learning Platform and some tips for making accessible content.

Cover

Only one cover image is required for book titles on O’Reilly Learning. The ingestion process will create other sizes as needed. The cover image requirements are:

  • .jpg and .png images are accepted. Other formats will fail QA.

  • Minimum width of 400 pixels

  • RGB or CMYK color encoded

  • File named FPID.jpg or FPID.png

Metadata

The metadata XML file provides details to the ingestion system about the work as a whole, such as title, author and copyright. The metadata file must be named FPID.xml. The following section lists the elements of a metadata file, presented in the order they should appear in a metadata file.

Elements in the following list set in red are required.

XML Header

The following XML version header must be included at the top of each metadata.xml:

<?xml version="1.0" encoding="utf-8"?>

<safarimeta>

The <safarimeta> tag is the first tag after the header and is required in all metadata files submitted to O’Reilly Learning ingestion. This tag has two attributes that help us identify and classify the content.

<safarimeta fpi="1234567890123" format="book">

FPI

The fpi attribute (the Formal Public Identifier, more commonly referred to as the FPID) is the official designation for the work in the O’Reilly Learning platform. It is typically the ISBN13 without hyphens. The Ebook ISBN13 is preferred, but you may also use the Print ISBN13. For content that has no ISBN, the publisher should assign one. If you are unsure or need help to create FPIDs, email the Content Team and we’ll be happy to help.

In addition, FPIDs must:

  • be unique.

  • be at least 5 characters in length.

  • begin with 5 leading digits.

  • NOT begin with 0 or 66666.

  • NOT contain more than 19 characters.

  • NOT contain punctuation.

  • And finally, all alphabetical characters must be UPPERCASE.

Format

The format attribute of the <safarimeta> tag defines the type of content being submitted. For this guide, we’re only concerned with book.

Important
 Using the video format for a book will cause the book to fail ingestion so please make sure to tag all of your incoming book titles as book.

<isbn>

<isbn> is the true 13-digit ISBN, including hyphens. No spaces should be included:

<isbn>978-1-4493-2914-3</isbn>

<title>

A <title> element is required in metadata. Place it immediately following the <isbn> element, for example:

<isbn>978-1-4493-2914-3</isbn><title>ePub 3 Best Practices: Optimize Your Digital Books</title>

The following requirements ensure consistent title presentation in the UI:

  • Do NOT use all caps.

  • Do NOT move the words "A", "An", and "The" to the end of the titles. The system ignores these words in alphabetical sorts.

Yes:

<title>The eBook Development Guide</title>

No:

<title>Ebook Development Guide, The</title>

Edition

Provide the edition number at the end of the title. For example:

<title>The Holy Grail of Network Storage Management, 2nd edition</title>

  • Use the number (2nd Edition) instead of the word (Second Edition) in <title>.

  • Do NOT use identifiers for 1st editions. Doing so creates confusion for users who may assume there is a 2nd Edition available, which is not always the case.

You should also provide the edition number as a numeric value in the <edition> tag (see <edition>).

<language>

The <language> tag identifies the language of a title. For example, for English a publisher would include:

<language>en</language>

or, for German, the tag would be:

<language>de</language>

If the <language> tag does not appear in the metadata, the system will automatically assume the work is in English.

The following languages are currently supported:

  • Chinese Simplified (zh-hans)

  • Chinese Traditional (zh-hant)

  • Dutch (nl)

  • English (en)

  • French (fr)

  • German (de)

  • Italian (it)

  • Japanese (ja)

  • Korean (ko)

  • Polish (pl)

  • Portuguese (pt)

  • Russian (ru)

  • Spanish (es)

Language codes follow ISO 639-1.

<edition>

The <edition> tag is used to differentiate multiple editions of the same title in a list of titles. Edition should use numerals, eg. 1, 2, etc. In this tag, first editions are designated as "1", unlike the edition number in the title.

<edition>2</edition>

<authorgroup>

An XML group named <authorgroup> should appear next in your metadata. This group can include <author>, <firstname>, <surname>, <othername>, <authorblurb> sub-tags, as desired:

<authorgroup>
    <author>
        <firstname>Jason</firstname>
        <surname>Hamon</surname>
    </author>
</authorgroup>

<author>

The <author> tag group must be repeated for each author in the title and should include <firstname> and <surname>. You can also include a middle name or middle initial using <othername>. No extra spacing or punctuation should be included; for example, there is no need to include spacing to separate multiple authors.

Non-human authors should be coded as:

<author>
    <othername>Hamon Press</othername>
</author>

Following are examples of how author elements are rendered.

  1. Where the <othername> contains pre-expanded content that should be rendered as-is. For example:

    <author>
    <firstname/>
    <surname/>
    <othername>Hamon, Jason</othername>
</author>

    Should render as: Hamon, Jason

    Empty tags may be ignored.

  2. Where the author has a middle name or initial. For example:

    <author>
    <firstname>Tom</firstname>
    <surname>Savage</surname>
    <othername>V.</othername>
</author>

    Should render as: Tom V. Savage

    Note that the rendering order may be different than the tag order within the author element.

<authorblurb> is an optional element. It may be provided for each individual author (i.e., within the <author> element) or once per book. If only one per book is provided, the URL attribute should point to a page containing information on all authors for a particular book:

<authorblurb url="http://wherever"/></authorgroup>

The ingestion engine will always try to normalize the name into the appropriate tags. If you add an <othername> that looks like a human name like:

<othername>Jason Jonathan Hamon</othername>

The ingester will break it apart into the <firstname> <othername> <surname> tags as appropriate. This can produce unintended results, so you should always use the appropriate tags for their respective name parts and only use <othername> with an associated role or as a company name.

<pagenums>

For books, <pagenums> is the number of pages in the print book:

<pagenums>564</pagenums>

<rights>

The <rights> tag contains the copyright line for the title. This must include the copyright symbol (©), year, and name of holders. Do not include trailing punctuation.

<rights>Copyright © 2017 O'Reilly Media, Inc.</rights>

or:

<rights>© 2017 Smith Technology, a part of Brown Learning</rights>

<pubdate>

<pubdate> is the title’s date of publication. Spell out the month in full:

<pubdate>April 16, 2015</pubdate>

If only the publication month is available, use the first of the month, for example:

<pubdate>April 1, 2015</pubdate>

<copyright_year> is the title’s year of publication, given as the four-digit year:

<copyright_year>2012</copyright_year>

<publisher>

The publisher XML group specifies the name of the publisher and imprint for the title.

<publishername> is the name of the publisher’s division responsible for the publication of the title. This field determines the publisher name displayed to users on O’Reilly Learning so it should represent the brand. It’s typically the same name as displayed on Amazon catalog pages.

<publisher>
    <publishername>O’Reilly Media, Inc.</publishername>
    <imprintname>O’Reilly Media</imprintname>
</publisher>

<description-short>

The contents of the <description-short> field are properly formatted XHTML of an abstract of the title. HTML and plain text are also accepted. This content will appear on the title’s catalog page in the user interface.

<description-short>
    <p>Description goes here</p>
</description-short>

HTML markup can be used in <description-short>, provided that it is enclosed in a CDATA section and within a CDATA tag:

<description-short>
    <![CDATA[ ANY HTML ]]>
</description-short>

Please note the following guidelines for using HTML markup for descriptions:

  • The CDATA section and tag should be used even with valid, well-formed HTML.

  • Some HTML elements are reserved by the system and not allowed as part of description ingestion. Most notably, h1 and h2 elements cannot be used. However, h3 through h6 elements may be used to structure thorough descriptions if desired.

  • Character entities are supported, but numeric is preferred (e.g., &#169; instead of &copy; for the copyright sign); ampersands must be encoded &amp;.

Note

Unicode characters, as used by "smartening" punctuation, often translate badly when ingested. The most common errors are:

apostrophe

Use the ' key or &apos;. Single quotation and accent marks cannot be used.

quotation

Use the " key or &quot; to open and close quotes. Smart quotes, left and right double-quotation cannot be used.

em dash

Use &mdash;. There is no substitute, however you may use multiple hyphens. For example ---

en dash

Use &ndash;. There is no substitute, however you may use multiple hyphens. For example --

<msrp>

This tag contains the publisher’s suggested retail price of the title, expressed in U.S. dollars, with two decimal places and without the dollar sign ($). If no print version is available, use the retail price of the electronic version. *The PSRP is the retail price and not the institutional/library price*. This field cannot be left empty nor can it be set to 0.00. O’Reilly Learning does not accept content that is freely available elsewhere in the market, with few exceptions.

<msrp>29.99</msrp>

<aliases>

A list of alternate ISBNs associated with the same product (e.g., the print ISBN of the provided ebook).

<aliases>
    <alias type="isbn" label="Print ISBN-10" name="1137024223" display="1-13-702422-3"/>
    <alias type="isbn13" label="Print ISBN-13" name="9780137024223" display="978-0-13-702422-3"/>
    <alias type="isbn" label="Web ISBN-10" name="1137014163" display="1-13-701416-3"/>
    <alias type="isbn13" label="Web ISBN-13" name="9780137014163" display="978-0-13-701416-3"/>
</aliases>

or:

<aliases>
    <alias type="other" label="Part Number" name="X0839351" display="X0839351"/>
</aliases>

<alternative_formats>

A list of ISBNs that refer to content related to the submitted work but in another format (e.g., the ISBN for the audiobook of the submitted book).

<alternative_formats>
    <alternative_format identifier="66666LNKEDBOOK01" />
</alternative_formats>

<relatedfiles>

The <relatedfiles> element is optional and is used for links to companion material, reference material, or other resources you want to make available to O’Reilly users. The links are displayed under the Publisher Resources heading on the product page.

There are several flavors of <relatedfiles> links:

Errata Page

unpublished errata for the title

Publisher Support

your Contact Us page

Publisher Website

your home page

Supplemental Content

a page where users can find companion material referenced in the title e.g., code examples

Other

anything else you want to make available

Under the <relatedfiles> element are several sub-fields:

<filegroup>
     <description>
            <cdata>Supplemental Content</cdata>
      </description>
      <ulink url="http://examples.oreilly.com/0636920028154/">Supplemental Content</ulink>
</filegroup>

You’ll tell us what kind of link it is in the description and the link text. An entry for a Publisher Website link would look like this:

<filegroup>
      <description>
            <cdata>Publisher Website</cdata>
      </description>
      <ulink url="http://oreilly.com/catalog/0636920028154">Publisher Website</ulink>
</filegroup>

Include multiple <filegroup> tags for multiple links:

<relatedfiles>
   <filegroup>
         <description>
            <cdata>Publisher Website</cdata>
         </description>
         <ulink url="http://oreilly.com/catalog/0636920028154">Publisher Website</ulink>
      </filegroup>
      <filegroup>
         <description>
            <cdata>Errata Page</cdata>
         </description>
         <ulink url="http://oreilly.com/catalog/0636920028154/errata">Errata Page</ulink>
      </filegroup>
</relatedfiles>

</safarimeta> (End Tag)

An end tag must be used to indicate the conclusion of the FPID.xml file:

</safarimeta>

Sample Metadata File 

<?xml version="1.0"?>
<safarimeta fpi="12345METADATA" format="book">
    <title>Sample Metadata</title>
    <rights>© Safari Books Online 2015</rights>
    <copyright_year>2015</copyright_year>
    <msrp>42.00</msrp>
    <edition>1</edition>
    <pubdate>February 2, 2015</pubdate>
    <isbn>978-1-4919-0172</isbn>
    <pagenums>825</pagenums>
    <language>en</language>
    <authorgroup>
        <author>
            <firstname>Sally</firstname>
            <surname>Safari</surname>
        </author>
    </authorgroup>
    <publisher>
        <publishername>Safari Books Online</publishername>
        <imprintname>Safari Books Online</imprintname>
    </publisher>
    <description-short>
        <p>Welcome to the wonderful world of sample metadata. This sample metadata will get you started on the right path to making sure your submissions to the O'Reilly Learning platform are as accurate as possible and can be uploaded with as little effort (and headache) as possible.</p>
    </description-short>
    <relatedfiles>   
         <filegroup>
             <description>
                 <cdata>Publisher Website</cdata>
             </description>
             <ulink url="http://oreilly.com/catalog/0636920028154">Publisher Website</ulink>
         </filegroup>
         <filegroup>
             <description>
                 <cdata>Errata Page</cdata>
             </description>
             <ulink url="http://oreilly.com/catalog/0636920028154/errata">Errata Page</ulink>
         </filegroup>
    </relatedfiles>
</safarimeta>