How to Validate Your Epubs to Ensure They Are CORRECT

If you already know how to generate your own custom epubs, the next step is to verify that the generated files are free of errors. To do this, I used the following tool: EpubCheck, from the W3C organization, which manages all the standards related to EPUBs:

https://www.w3.org/publishing/epubcheck/

Why is validation important?

I really didn't realize this part of EPUB generation was so important. It turns out that, in addition to making sure your book looks good in apps like Calibre, it also needs to be structurally sound, especially if you're uploading it to platforms like Google Play Books or Apple Books.

In my case, I had problems with the EPUB when uploading it to Google Play. It threw up errors and suggested I contact support. I discovered all of this precisely because I wasn't properly validating the EPUB files.

A professional tool: EpubCheck (W3C)

That's why I decided to use EpubCheck, a very reliable tool that validates whether the file complies with standards. Just because an EPUB opens in Calibre doesn't mean it's valid. Some errors can prevent it from working properly on other platforms, or even prevent the upload from being accepted.

Also, as a professional, it's important to get things right from the start. This tool has been very helpful for me in verifying that everything is correct. Even if you're using automated tools to generate EPUBs, I recommend running this validation check for a "double check."

How to install and use EpubCheck?

EpubCheck is a tool written in Java. Therefore, you need to have OpenJDK or Java installed, or you can directly use the one included in Android Studio (which was my case).

I haven't developed in Java in a long time, so I didn't have Java installed natively. Since Android Studio already has it built-in, I simply used that one.

On Mac, OpenJDK was already pre-installed. On Windows, I simply accessed the Android Studio Java folder and ran it from there.

Steps to use EpubCheck

Download the EpubCheck package from the official site I shared at the beginning of the post.

• Unzip the ZIP file, and it will generate a folder with several files.
• Find the file named epubcheck.jar.
• Use a terminal or command line to run the tool. The basic command would be:

$ java -jar epubcheck.jar route/del/file.epub

In my case, I had to provide the full path to the Android Studio Java executable, as I didn't have Java installed on my system.

When you run the command, if the program takes a while, that's a good sign: it's processing the file. If everything is correct, you won't see any errors. If it finishes too quickly, there may be a problem with the path or it may not be finding the file.

For a correct file, the program simply indicates that there are no errors. However, when there are errors, it displays them clearly.

For example, one of my books had errors because I customized a font but hadn't physically included it in the EPUB, even though I did reference it in the CSS. EpubCheck clearly indicated this and allowed me to quickly correct it:

ha encontrado en el EPUB.
ERROR(RSC-007): I:/descargas/librosacademia/laravel/es/laravel.epub/OEBPS/chapter22.xhtml(42,13): El recurso referenciado "OEBPS/fonts/SUSE-ExtraBold.ttf" no se ha encontrado en el EPUB.
ERROR(RSC-007): I:/descargas/librosacademia/laravel/es/laravel.epub/OEBPS/chapter22.xhtml(47,13): El recurso referenciado "OEBPS/fonts/SUSE-Regular.ttf" no se ha encontrado en el EPUB.
ERROR(RSC-007): I:/descargas/librosacademia/laravel/es/laravel.epub/OEBPS/chapter22.xhtml(52,13): El recurso referenciado "OEBPS/fonts/SUSE-SemiBold.ttf" no se ha encontrado en el EPUB.

Prueba finalizada con errores
Mensajes: 0 errores fatales / 405 errores / 0 advertencias / 0 indicaciones

EPUBCheck completado

C:\Users\andre>
C:\Users\andre>
C:\Users\andre>
C:\Users\andre>
C:\Users\andre>"C:\Program Files\Android\Android Studio\jbr\bin\java.exe" -jar "I:\descargas\epubcheck-5.2.1\epubcheck.jar" "I:\descargas\librosacademia\mac\alpine\es\Primeros pasos con Alpine.js, tu nuevo y ligero framework JavaScript.epub"
Validación usando la versión de reglas epub 2.0.1.

I've also had files with errors like misplaced <div> tags or missing files within the EPUB. Sometimes this is caused by editors like Sigil, or even when you export from Google Docs and a reference is lost. EpubCheck shows you exactly which file has the problem and on which line it occurs:

ERROR(RSC-005): I:/descargas/librosacademia/mac/alpine/es/Primeros pasos con Alpine.js, tu nuevo y ligero framework JavaScript.epub/OEBPS/chapter3.xhtml(670,2115): Error al analizar el archivo: el elemento "div" no se permite aquí; se esperaba el elemento final de etiqueta, texto o elemento "a", "abbr", "acronym", "applet", "b", "bdo", "big", "br", "cite", "code", "del", "dfn", "em", "i", "iframe", "img", "ins", "kbd", "map", "noscript", "ns:svg", "object", "q", "samp", "script", "small", "span", "strong", "sub", "sup", "tt" o "var" (con xmlns:ns="http://www.w3.org/2000/svg")
ERROR(RSC-005): I:/descargas/librosacademia/mac/alpine/es/Primeros pasos con Alpine.js, tu nuevo y ligero framework JavaScript.epub/OEBPS/chapter5.xhtml(603,227): Error al analizar el archivo: el elemento "div" no se permite aquí; se esperaba el elemento final de etiqueta, texto o elemento "a", "abbr", "acronym", "applet", "b", "bdo", "big", "br", "cite", "code", "del", "dfn", "em", "i", "iframe", "img", "ins", "kbd", "map", "noscript", "ns:svg", "object", "q", "samp", "script", "small", "span", "strong", "sub", "sup", "tt" o "var" (con xmlns:ns="http://www.w3.org/2000/svg")
ERROR(RSC-005): I:/descargas/librosacademia/mac/alpine/es/Primeros pasos con Alpine.js, tu nuevo y ligero framework JavaScript.epub/OEBPS/chapter5.xhtml(603,1057): Error al analizar el archivo: el elemento "div" no se permite aquí; se esperaba el elemento final de etiqueta, texto o elemento "a", "abbr", "acronym", "applet", "b", "bdo", "big", "br", "cite", "code", "del", "dfn", "em", "i", "iframe", "img", "ins", "kbd", "map", "noscript", "ns:svg", "object", "q", "samp", "script", "small", "span", "strong", "sub", "sup", "tt" o "var" (con xmlns:ns="http://www.w3.org/2000/svg")

You can also use Android Studio, which has a version of Java installed; here are some commands you can run:

--- PC
"C:\Program Files\Android\Android Studio\jbr\bin\java.exe" -jar "I:\descargas\epubcheck-5.2.1\epubcheck.jar" "I:\descargas\librosacademia\laravel\es\laravel.epub"

--- MacOS
java -jar "/Volumes/My Passport/archivos/descargas/libros ready/epubcheck-5.2.1/epubcheck.jar" "/Volumes/My Passport/archivos/descargas/libros ready/flask/es/Primeros pasos con Flask 3.epub"

Conclusion

In summary:

• Download EpubCheck; it's a free, professional, and reliable tool.
• Install Java or use Android Studio if you already have it.
• Run the validation with the command java -jar epubcheck.jar followed by the file path.
• Correct any errors that appear. It's better to be safe than sorry when uploading a book with problems.