Safari Documentation
Metadata
Metadata is descriptive product data (including MSRP, author, page count, and publisher) that is crucial for making your title discoverable on Safari. For FTP title uploads, the metadata should be included in a file named “metadata.xml”. Alternatively, you can enter your metadata manually via the Safari Content Manager (SCM).
Metadata Content
The file metadata.xml contains the following content, listed in preferred order. All elements are required unless otherwise noted.
NOTE: Metadata.xml should not contain a DTD reference when uploaded. If a DTD is included for validation purposes, it should be removed before uploading the files. Special character entities (–, for example) defined in DocBook should be expanded to their UTF-8 code point. Care should also be taken not to include special Microsoft Word characters that are not valid UTF-8 characters (like the curly double quote). These are sometimes introduced via copy/paste into the metadata (such as the <description-short> text).
XML Header. The following XML version header should be included at the top of each metadata.xml:
<?xml version="1.0" encoding="utf-8"?>
FPI. The fpi attribute (more commonly referred to as the FPID), or Formal Public Identifier, is the official Safari designation for the book or video. It is typically the ISBN without hyphens, and the ebook-13 ISBN is preferred. Any alphabetical characters should be uppercase. For content that has no ISBN, the publisher must ensure that the FPID is not currently in use.
The FPID must begin with 5 leading digits, with a maximum of 20 digits, and should not contain hyphens:
<safarimeta fpi="1234567890123">
Version (optional). <version> is the true version number of this combination of content and metadata. The version number is optional but is recommended: it should be changed for every upload so that updates can be tracked on the staging and live servers.
By convention, version numbers should modify the leading (major) number when content changes and the minor number when metadata changes:
<version>1.2</version>
The version appears along with the last updated date on the staging server. The version number also appears in the public gateway for live and staging servers. This enables publishers to query the servers and determine which "version" of a book we are seeing.
Grbook. Originally this tag was added in order to distinguish that a book is a Print Fidelity title. This tag must be used when HTML is only intended for 508 compliance. The combinations of HTML and Print Fidelity support are:
- no <grbook/> element, or an empty <grbook/> element: The system will query the supplied formats for the title and insert the proper tagging.
- <grbook htmlview="none"/>: Graphically Rich (print-fidelity) view is available, HTML is not supported.
- <grbook htmlview="only508"/>: Graphically Rich (print-fidelity) view is available, HTML is not supported except where used for 508 compliance.
ISBN. <isbn> is the true 13-digit ISBN, including hyphens. No spaces should be included:
<isbn>1-23456-789-0</isbn>
Title. A book <title> element is required in metadata. Place it immediately following the <isbn> element, for example:
<isbn>9781449377243</isbn>
<title>Mac OS X Snow Leopard: The Missing Manual, 2nd Edition</title>
NOTE: For EPUB-sourced titles, the <title/> element in metadata will supercede the book’s title in the EPUB file. But if no title is provided in metadata, the title in the EPUB file will be used on Safari.
The following requirements ensure consistent book 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 Holy Grail of Network Storage Management</title>
No: <title>Holy Grail of Network Storage Management, The</title>
Editions. Please 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 1st edition identifiers. This creates confusion for users who see this and assume that there is a 2nd edition available, which is not always the case.
You will also need to provide the edition number as a numeric value in <edition> (see the Edition entry below).
pubproductid (optional). This optional element is for publishers who would like to submit their own identifier for reporting purposes. The system will then return this id in the royalty reports, to allow the publisher to easily tie the report data back to their proprietary databases. To support this, there is an optional, updateable <pubproductid> element after the <isbn> element.
<safarimeta fpi="9780470372258">
<isbn>978-0-470-37225-8</isbn>
<pubproductid>IMR00123456</pubproductid>
<edition>3</edition>
<rights>Copyright © 2008 Dave Crenshaw</rights>
Language. <language> identifies the language of a book. For example, a publisher would include
<language>en</language>
or
<language>de</language>
If the tag is absent from metadata, the system will automatically assume
<language>en</language>
The codes for languages are taken from ISO 639: http://www.utoronto.ca/webdocs/HTMLdocs/Book/Book-3ed/appe/iso639.html
Edition. Edition is used to differentiate multiple editions of the same book in a list of titles. <edition> should use numerals, for example 1, 2, etc.
<edition>2</edition>
Authorgroup. An XML group titled <authorgroup> should then be displayed with the <author>, <firstname>, <surname>, <othername>, <authorblurb> sub-tags, as desired:
<authorgroup>
....<author>
........<firstname>David</firstname>
........<surname>Metcalfe</surname>....</author>
Author. <author> should be repeated for each author of the book. Other elements may be used as appropriate to define the author name: <othername> (with optional role="mi" for middle initial), <honorific>, <lineage> and <affiliation>. No extra spacing or punctuation should be included; for example, there is no need to include spacing to separate multiple authors.
Corporate authors should be coded as:
<author>
<othername>Logictran Press</othername>
</author>
Following are examples of how author elements are rendered. There are four broad forms of <author> tagging:
1. Where the <othername> contains pre-expanded content that should be rendered as-is. For example:
<author>
<firstname/>
<surname/>
<othername>Jones, Gareth</othername>
</author>
Should render as
Jones, Gareth
Empty tags may be ignored.
2. Where some punctuation has already been added. For example:
<author>
<firstname>Tom</firstname>
<surname>Savage - </surname>
<othername role="mi">V.</othername>
<othername role="affil">Santa Clara University</othername>
</author>
Should render as
Tom V. Savage - Santa Clara University
That is
<firstname> <othername role=”mi”> <surname> <lineage> <honorific> <othername role=”affil”>
with a single space between each. Note that the rendering order may be different than the tag order within the author element, and that all elements may not be present (e.g., don’t output anything for othername role="mi" is missing).
3. Where punctuation needs to be added. This is for the affiliation tag. For example:
<author>
<firstname>Arthur</firstname>
<surname>Aron</surname>
<affiliation>State University of New York at Stony Brook</affiliation>
</author>
Should render as
Arthur Aron - State University of New York at Stony Brook
That is, separate surname from <affiliation> with ‘ – ‘. Otherwise, render in the same order as in item (2) above.
4. Misspelled content. These are relatively rare, but rather than force book uploads, please treat <othername role="affl">, <othername role="afflliation">, <othername role="afiliation">, and <othername role="honorific"> exactly like <othername role="affil">.
Authorblurb (optional). This 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>
Pagenums. <pagenums> is the number of pages in the printed book:
<pagenums>256</pagenums>
Rights. Contains the copyright line for the book. This must include the copyright symbol (©), year and name of holders. There should be no trailing punctuation.
<rights>Copyright © 2010 Pearson Education, Inc.</rights>
or
<rights>© 2008 Course Technology, a part of Cengage Learning</rights>
If this information is omitted, “© Safari Books Online” will be displayed in the footer watermarks in downloaded PDF or EPUB files.
Pubdate. <pubdate> is the book’s date of publication. The month should be spelled out in full.
<pubdate>September 16, 2012</pubdate>
If only the publication month is available, use the first of the month, for example:
<pubdate>September 1, 2012</pubdate>
Copyright year. <copyright_year> is the book’s year of publication. It should be 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 book.
Publishername. This is the name of the publisher’s division responsible for the publication of a book. This field determines the publisher name displayed in the UI on Safari so it should represent the brand. It’s typically the same name as displayed on Amazon catalog pages.
Imprintname. This is usually identical to the <publishername>. In certain cases it can be used differently, for example, to flag a particular series in reports, but please check with Safari before entering a different value from <publishername>.
<publisher>
....<publishername>Que</publishername>
....<imprintname>Que</imprintname>
</publisher>
Description-Short. The contents of the <description-short> field is properly formatted XHTML of an abstract of the book. HTML and plain text are also accepted. This content will appear on the book’s catalog page in the user interface.
<description-short>
....<p>Description goes here</p>
</description-short>
HTML can be used in <description-short>, provided that it is enclosed in a CDATA section and within a cdata tag as follows:
<description-short><cdata><![CDATA[ ANY HTML ]]></cdata></description-short>
For HTML descriptions, character entities are supported, but numeric is preferred (e.g., © instead of © for the copyright sign); ampersands must be encoded: &. Note that the CDATA section and tag are needed even for valid, well-formed HTML.
MSRP. Contains the manufacturer's suggested retail price, expressed in U.S. dollars, with two decimal places and without the dollar sign ($). Cannot be left empty. If a book is free, use 0.00.
MSRP is coded as follows:
<msrp>29.99</msrp>
Points. This field indicates the number of slots the book should take on user bookshelves. Except for free content, this value must be set to 1 for all books. If points are not specified in metadata, the system will treat that as points=1.
Points are coded as follows:
<points royalty="all">1</points>
For free content, specify: <points>0</points>
Prevedition (optional). <prevedition> is an optional tag linking this book with its previous edition. Safari recommends this tag be used, as doing so will provide an indication to the user that a newer edition of a book is available, as shown below:
<prevedition fpi="9780596514822"></prevedition>
Classification (optional). <classification> is an optional tag indicating how the book should be classified on Safari. This tag is used internally by Safari; do not use <classification> without confirmation from Safari. One or multiple classifications separated by “|” may be provided in the same element, for example
<classification>itil</classification>
or
<classification>cisco|academicexcluded</classification>
Graphic widths. Various versions of the book cover are specified in metadata.xml. The width is the maximum allowed width. The depth (or height) is a value that maintains the original image’s aspect ratio for the designated width. The attribute roles and fileref naming should be specified as below. See Cover Images for a detailed discussion of these specs.
<graphic width="76" depth="115" role="category-page" fileref="FPID_xs.jpg"/>
<graphic width="145" depth="219" role="book-page" fileref="FPID_s.jpg"/>
<graphic width="42" depth="63" role="small-cover" fileref="FPID_cs.jpg"/>
<graphic width="500" depth="617" role="large-cover" fileref="FPID_large.jpg" />
Bibliomisc (optional). The optional <bibliomisc> element was modified for Safari 6.0 and is now only used to display the Buy Print Version button on the catalog page. The URLs are not checked for correctness (nor existence), so should be verified independently before uploading books.
Buyprint. Information must be provided regarding the location where users may purchase print versions of the book (usually the publisher's own website):
<bibliomisc role="buyprint" url="wherever"/>
Bookstructurelist. <bookstructurelist> controls downloads for offline viewing, and preview chapters. For dual-format titles, it also sets up the TOC on Safari and helps enforce a match between the EPUB TOC and the PDF bookmarks to create the Safari TOC.
A variety of attributes can be used with <bookstructurelist> to specify file formats and roles, chapter matching, previews, and download availability and token costs. Each are discussed in more detail below.
- role: identifies the unit as the book, a part, or a chapter
- format: identifies file format as either PDF, EPUB, or MOBI
- download: whether the unit can be downloaded
- tokens: when role=“book”, identifies the number of tokens needed to download the whole book; when role=“chapter” and format=“PDF”, identifies the number of tokens needed to download the chapter. (The EPUB file format does not allow for chapter downloads; only the PDF file format allows for chapter downloads.)
- linkid: identifies the navPoint ID in the EPUB toc.ncx file
- title: identifies the title of the unit
- view: when value is “public”, identifies the unit as fully viewable sample content to anonymous viewers
Bookstructureunit. Use bookstructureunit role to specify whether an item is the book, part, or chapter.
<bookstructurelist>
....<bookstructureunit role="book" tokens="10">
....<file url="e-formats/9781780171340.pdf" format="pdf"/>
....<bookstructureunit role="part" linkid="p01" title="Part 1: A Look at Java" download="yes" tokens="3"/>
....<bookstructureunit role="chapter" linkid="ch01" title="Chapter 1: Your First Taste of Java" download="yes" tokens="1"/>
....<bookstructureunit role="chapter" linkid="ch02" title="Chapter 2: Language Fundamentals" view="public" download="yes" tokens="1"/>
....<bookstructureunit role="chapter" linkid="ch03" title="Chapter 3: Statements" download="yes" tokens="1"/>
....<bookstructureunit role="chapter" linkid="appA" title="Appendix A: Objects and Classes" download="yes" tokens="1"/>
</bookstructurelist>
You also use bookstructureunit to specify alternate file formats for book downloads.
Sample or Preview Content. Safari strongly encourages publishers to include one sample chapter per title for promotional purposes. The view attribute allows you to specify a free sample chapter. The chapter(s) specified with view="public" will be fully viewable online to nonsubscribers (but not downloadable.) A button will appear next to these chapters in the TOC. The normal preview mechanisms still apply to the content not marked with view="public".
<bookstructurelist>
....<bookstructureunit role="chapter" linkid="navpoint-11" title="Chapter 1: Your First Taste of Java" download="yes" tokens="1"/>
....<bookstructureunit role="chapter" linkid="navpoint-17" title="Chapter 2: Language Fundamentals" view="public" download="yes" tokens="1"/>
</bookstructurelist>
Downloads. Whole books and/or chapters can be made available for download and their token cost specified through the download and tokens attributes.
To allow an entire book to be downloaded as a PDF and paid for by tokens, bookstructureunit role is "book" and the tokens attribute contains the cost of the download.
The tokens attribute specifies how many tokens an end user must spend to purchase the EPUB or PDF. In general, each chapter requires one token, but publishers are free to set the value to be any integer.
The following specifies that a full book can be downloaded, but individual chapter downloads are not supported:
<bookstructureunit>
....<bookstructureunit role="book" tokens="10">
....<file url="e-formats/9781780171340.pdf" format="epub"/>
....<bookstructureunit role="chapter" linkid="navpoint-11" title="Chapter 1: Your First Taste of Java" download="no"/>
....<bookstructureunit role="chapter" linkid="navpoint-17" title="Chapter 2: Language Fundamentals" download="no"/>
....<bookstructureunit role="chapter" linkid="navpoint-29" title="Chapter 3: Statements" download="no"/>
</bookstructureunit>
If a book is offered for download as a full book AND as separate chapter downloads, both syntaxes are used together as shown:
<bookstructureunit>
....<bookstructureunit role="book" tokens="10">
<file url="e-formats/9781780171340.pdf" format="pdf"/>
........<bookstructureunit role="chapter" linkid="ch01" download="yes" tokens="1"/>
........<bookstructureunit role="chapter" linkid="app01" download="yes" tokens="1"/>
</bookstructureunit>
Note that it’s not necessary to include download="yes". As long as tokens are specified, download="yes" is implied.
Free downloads. If tokens=”0” is supplied, this will result in a free download.
EPUB and MOBI downloads. In addition to PDF download, publishers may choose to make mobile formats available for download. Currently two formats are defined: EPUB (file extension of .epub) and MOBI (file extension .mobi or .prc—either one will work but it should match the file that you submit). The list of available formats may be extended in the future, but only the file types defined in this specification may be provided. Providing an EPUB for the Safari HTML view does not automatically mean the publisher is making the EPUB available for download too.
MOBI and EPUB formats may be provided at the book level only. The price for mobile downloads is exactly the same as for the whole-book PDF download.
If additional formats are provided, the bookstructureunit should list the file formats and files:
<bookstructurelist>
<bookstructureunit role="book" tokens="4">
........<file format="epub" url="e-formats/9780321601629.epub"/>
........<file format="mobi" url="e-formats/9780321601629.mobi"/>
<bookstructureunit role="part" linkid="navpoint-9" title="Part 1: A Look at Java" download="yes" tokens="1"/>
<bookstructureunit role="chapter" linkid="navpoint-11" title="Chapter 1: Your First Taste of Java" download="yes" tokens="1"/>
........<file format="epub" url="e-formats/9780321601629.epub "/>
</bookstructurelist
The mobile format files should be uploaded using the same process as extras: the content must be uploaded to an FTP server provided by Safari (known as the Extras server). To use this feature you must request a login/password on ftp://safaridata.bvdep.com. Within this server, create a folder for the book using the FPID of the book and a sub-folder for content named /e-formats. Then upload your content.
Safari provides visible watermarking (no invisible watermarking) to downloaded EPUB files in the form of custom footers at the end of each chapter section (or chapter-equivalent section). There is no watermarking added to MOBI downloads—files are delivered as provided by publishers.
Aliases. The <aliases> element provides a list of alternate ISBNs that resolve to the same location. For example, if 0131287958 is the e-book ISBN and 0131330055 is the package ISBN for 0131451448, then any of these can be used to navigate:
http://search.safaribooksonline.com/0131451448
http://search.safaribooksonline.com/0131287958 — redirects to http://search.safaribooksonline.com/0131451448
http://search.safaribooksonline.com/0131330055 — redirects to http://search.safaribooksonline.com/0131451448
On rare occasions, an ISBN changes and this same technique would allow a new ISBN to redirect to the original URL. This approach is much easier than deleting the original ISBN.
Only one of these URLs (the one built from the publisher-supplied FPID) will be generated by Safari, so once the customer navigates to a book using one of these aliases all subsequent navigation will use the FPID based URLs. (For example, if a URL appears at the bottom of the cover page, this URL will continue to be generated from the FPID.)
The redirection mechanism should be flexible enough to address URLs with parameters as in
http://bowindex5.bvdep.com/0131447645/?portal=logictran
The list of alternate ISBNs will be provided as an additional element of the metadata.
<aliases>
<alias type="isbn" label="Print ISBN-10" name="0137024223" display="0-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="0137014163" display="0-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>
| Attribute | Description | Values | Required |
| name | Provides the alias. Usually an ISBN, but could be another identifier that is important to the publisher. For example, IBM Redbooks have a form number SG24-6315-00. |
CDATA For ISBNs, the dashes should be removed. |
Y |
| type | Identifies the type of the alias. If type="isbn" or type="isbn13" is used, this alias should be searchable in the ISBN search mechanism. | CDATA | N |
| label |
This is the label for the alias to be used in any case where the alias is displayed. If not provided, this alias should not be displayed. When multiple ISBNs are displayed, (on the cover page) they are displayed in the same order as they appear in the aliases element. Supported labels are: |
CDATA | N |
| display | This is the rendering of an alias as it would appear on the cover page. Used to provide hyphenated ISBNs. | CDATA | N |
The following sample shows a book with a print, ebook, and package ISBN:
<aliases>
<alias type="isbn" label="Print ISBN-10" name="0137024223" display="0-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="0137014163" display="0-13-701416-3"/>
<alias type="isbn13" label="Web ISBN-13" name="9780137014163" display="978-0-13-701416-3"/>
<alias type="isbn" name="0205464718"/>
</aliases>
All are type="isbn" or type="isbn13", so all would be supported in the search by ISBN. The ones with labels are listed on the cover page using the supplied labels in place of the current <isbn> element display.
The rendering would be:
Comingsoon. The <comingsoon> element is optional in the metadata. If present, it indicates that the content of the book is not yet available. This allows for the creation of coupons, but otherwise the book is not visible and will not appear in searches. Example:
<comingsoon/>
The process for submitting a book with the <comingsoon> element follows the normal staging and uploading process. The associated book content would be a minimal book containing only a title.
<book fpi="0131445960">
<title>Astronomy Today, 5th Edition</title>
</book>
Exclusive (optional). This is an optional element that can appear anywhere in the metadata. Some publishers have signed exclusive agreements with Safari in which their books are either always exclusively on Safari, or are exclusive for a limited time. These titles are identified as follows:
<exclusive>yes</exclusive>
Exclusiveexp. If the exclusive agreement has an end date, an optional <exclusiveexp/> can be used:
<exclusiveexp>01/15/2010</exclusiveexp>
Dependencies (optional). This is an optional element for a book on Safari that links to a corresponding video title on Safari. This metadata ensures that if the book is on a user’s bookshelf, the user will have access to all of the content of the video via the links in the book.
<dependencies>
<dependency fpi="vvvvvvvvvvvv" />
</dependencies>
where vvvvvvvvvvvv is the FPID of the video. Only the video FPID appears here, not the individual clips. See the Interactivity on Safari section for more information on how to use it and how to add inline links to video to your books.
Related files. Please see the Companion Content/Extras section for details on <relatedfiles/>.
End tag. An end tag must be used to indicate the conclusion of the metadata.xml file:
</safarimeta>
Metadata Requirements for Short Cuts
Short Cuts are designed to provide more complete and timely coverage of technology because either 1) the topic covered is too early in the technology life cycle to have a book published, or 2) the topic is too focused to be covered separately in a book.
To designate a title as a Short Cut, simply include the metadata element of
<shortcuts/>
Short Cuts are browsable separate from other types of content, but they will also come up in search.