Validate EPUB and iBooks Author ebook files for Apple iBooks Store

• Tweet
• Email
• Sumo

• Tweet
• Email

Your ebook is finished! You did your homework, fixed all the nasty errors that epubcheck threw at you, and your ebook is done. The only remaining step is to send it to Apple’s review team and cross your fingers.

A week passes and…crap, Apple rejects the file for some technical reason:

> ERROR ITMS-5107: Fixed layout books must identify the start of the book’s main content by including a guide (EPUB 2) or Landmarks (EPUB 3), or provide a custom sample. For more information see the iBookstore Asset Guide in the Deliver Your Content module on iTunes Connect.

What?! epubcheck did not warn you of that, did it? No, it didn’t, because the error reported is actually not a requirement in the EPUB 3 specification. It is, nevertheless, a requirement of the iBooks Store as stated in Apple’s iBooks Asset Guide. That document describes, among other things, stuff that is required by Apple but not necessarily by the EPUB 3 specification nor, therefore, by epubcheck.

Grrr! So now you have to fix that, send the ebook to Apple all over again, and wait more time for your file to be reviewed, hoping this time you did not miss anything else required by Apple but not enforced by epubcheck. There goes another week you will never get back.

The thing is, you could actually have avoided that bummer had you used Apple’s automated online validator before sending the book to their human review team. That validation service provides instant results, and you can validate any book without even registering the book in iTunes Connect (which is what you—or your ebook distributor—do for any book that you want to sell through the iBooks Store). So do yourself a favor and test your books against Apple’s validator before sending them to the iBooks Store.

Using Apple’s ebook validator requires you to use the command line (i.e., the application Terminal in OS X or the Command Prompt in Windows), but fret not, it’s not that difficult. Here is how you do it.

Requirements

Apple ID

You need an Apple ID, and you need to enable iTunes Connect for iBooks for that account.

A word of caution: once you have done the above, in iTunes Connect go to Users and Roles and find what role your user has. If it is any other role than Read-only, I suggest that you create a new Read-only user for the purpose of validating books. You will be required to enter the password for the Apple ID in the command line every single time you attempt a validation. Sooner or later you will probably leave a trace of that password in the history of recently used commands, potentially becoming readable by anyone with local or remote access to your computer. The commands in this tutorial are written in a way to minimize the chances of that happening, but it’s better to be safe than sorry.

A Read-only user can change nothing in iTunes Connect except for his or her personal details, so by using this dumb Apple ID you further minimize the dangers of that password being compromised. A user with an Administrator role can revoke the credentials of any user at any time, but you’re better off not doing so for accounts with more important roles.

Transporter

Transporter is “Apple’s Java-based command-line tool used for sending content to the iTunes Store and App Store.” That is what its manual states, but it’s also currently the only interface to Apple’s ebook validation service. According to the manual, the tool supports the following operating systems:

• Apple’s OS X version 10.6 or later (64-bit system)
• Microsoft’s Windows XP (32 bit versions only)
• Red Hat Enterprise Linux (64-bit system)
• Solaris 10 (Intel, 64-bit system)

You can download the installer from iTunes Connect > Resources & Help. Choose it from the section titled “Book Delivery”. Choose the version appropriate for your operating system by clicking the icon next to “iTunes Transporter” that has the small arrow pointing downwards.

Validation

Follow these steps to validate an EPUB file or an iBooks Author ebook file:

1. If using OS X, launch Terminal. If using Windows, launch Command Prompt.

2. In the case of OS X (or any other UNIX-like system—the rest of this tutorial assumes a UNIX user knows what applies to you and what does not without mentioning it), copy the following and paste it into the Terminal window:

/usr/local/itms/bin/iTMSTransporter \
 -m validateRawAssets \
 -v critical -u

In Windows, copy and paste the following in the Command Prompt window:

"C:\Program Files\itms\iTMSTransporter.CMD" ^
 -m validateRawAssets ^
 -v critical ^
 -WONoPause true -u

Note that Windows’ Command Prompt does not let you paste with the usual keyboard shortcut ctrl + V. In order to paste, right-click the Command Prompt window and choose Paste.

Be careful not to add a carriage return at the end nor press Enter yet. We are not done with the command.

3. Add a space. Then type your Apple ID.

4. Add another space, type -assetFile then yet another space.

5. Drag the ebook from the Finder (in OS X) or the File Explorer (in Windows) into the command-line window. That should append the path of the file to the command, becoming something like this in OS X:

/usr/local/itms/bin/iTMSTransporter \
 -m validateRawAssets \
 -v critical -u myappleid -assetFile path/to/epub

and like this in Windows:

"C:\Program Files\itms\iTMSTransporter.CMD" ^
 -m validateRawAssets ^
 -v critical ^
 -WONoPause true -u myappleid -assetFile path/to/epub

6. Press Enter. _Yay!_

Transporter will respond with this steps:

1. It will attempt to autoupdate itself to the latest version.

2. It will prompt you to enter the password for your Apple ID:

myappleid's password:

Type the password. You will not see any visual feedback as you type. This is normal. Just type your password and press Enter.

3. After it uploads the book and attempts to validate, you will get a reply of success if the book is valid:

Summary

1 asset was validated successfully: 
EBOOK.EPUB

or a list of errors if the book is invalid:

Summary

1 asset was not validated successfully because it had problems:
EBOOK.EPUB
ERROR ITMS-9000: Book manifest file has a <spine><itemref idref="ch030_xhtml"> but no matching <manifest><item id="ch030_xhtml">

Note

Having to type your password each time you validate a book is admittedly a pain. Evaluate the benefits and risks of appending -p mypassword after step 3, where mypassword is the password for your Apple ID. If you provide Transporter with your password in the command line like this, it will not prompt you to enter it again each time. You can save the whole snippet with your password in it and repeat this process faster with less typing. Be aware, though, that doing this will leave the password recorded in the history of recent commands, potentially being readable by anyone with local or remote access to your computer.

About the Author

Jorge is Product Manager and Automation Tinkerer at Esdecómic Digital, an ebook conversion company based in Barcelona and specialized in digital children ebooks, comics and mobile apps for publishing clients. He tweets from time to time as @elmimmo_ mostly regarding ebook technologies.