How to Validate an EPUB File

Two levels of checking

There are two useful ways to check an EPUB, and they answer different questions.

• A quick structural check tells you whether the archive, the package file, the reading order, the navigation and the internal links are consistent. It answers: “Why won’t this book open, or why is a chapter missing?”
• A conformance check with W3C’s EPUBCheck program verifies the file against the whole specification, including content rules, CSS and accessibility metadata. It answers: “Will a retailer or library accept this?”

PDFSwift’s EPUB Validator is the first kind. It runs in your browser with no installation and no upload.

Running the quick check

1. Open the EPUB Validator and choose the book.
2. Press Validate EPUB.
3. Read the verdict and the counts of errors, warnings and notices.
4. Use the table: every row has a code, a plain description and the file in question.
5. Press Download report (JSON) if you want to keep the findings.

Reading the results

Errors are what you should fix first. Warnings, such as a file present in the archive but not in the manifest or an image fetched from the internet, are things some apps tolerate and others do not.

Fixing what it finds

The mechanical problems in the table can be repaired automatically. Use the EPUB Repair tool, which applies the safe fixes, lists each change, and validates the result again. Problems inside chapter content, such as malformed XML in the middle of a paragraph, need the chapter to be edited in an HTML or EPUB editor.

When you need a formal result

If you are submitting to a store, a distributor or a library, run EPUBCheck, the W3C’s reference validator. It needs Java. With Java installed, the command is:

java -jar epubcheck.jar yourbook.epub

The PDFSwift tools were tested against EPUBCheck: the books produced by the metadata editor, cover editor, repair tool and merge tool were checked with it and reported no errors. That does not mean every book they touch will be conformant. A book that was invalid for reasons the tools do not repair stays invalid, and EPUBCheck will tell you why.

Anatomy of a validation message

Whatever tool you use, each finding has the same parts: a code that identifies the rule, a severity, a message, and a location. EPUBCheck prints lines like ERROR(RSC-001): book.epub/OEBPS/content.opf(14,3): File "OEBPS/text/ch2.xhtml" could not be found. The PDFSwift validator gives you the same information in a table: code, message and file. When you ask for help in a forum, paste the code and the message; they point straight at the problem.

What a clean result means and what it does not

A book without errors is structurally sound: it will open in standards-compliant readers, its navigation works, and its links resolve. It does not mean the book is good. The text may be badly proofread, the images unreadable, the language wrong, or the CSS ugly. Validators check form, not quality.

A validation habit for anyone who makes EPUBs

1. Validate after every export from your authoring tool, not only at the end.
2. Fix errors in the source and export again, instead of patching the EPUB by hand each time.
3. Keep warnings under control. A warning today often becomes a rejection when a store tightens its checks.
4. Run formal EPUBCheck before submission, and keep its output with the release.

Where each tool fits