epubcheck es el validador de conformidad canónico de EPUB, mantenido por el DAISY Consortium y la comunidad del W3C. Lee tu archivo contra la especificación EPUB y reporta cada desviación como un ERROR o un WARNING, cada uno etiquetado con un código corto como RSC-005. Los códigos parecen crípticos, pero casi todos son mecánicos: un archivo que falta, un atributo en el lugar equivocado, o un recurso que no debería estar ahí.
Esta guía recorre las familias de error que realmente te vas a encontrar, qué causa cada una y su arreglo típico. La regla de oro: resuelve primero cada línea de ERROR — los errores rompen la conformidad y pueden impedir que los lectores abran el libro — y luego trabaja las líneas de WARNING. Origami usa el mismo motor de epubcheck, explica cada hallazgo en lenguaje llano y ordena los bloqueantes arriba para que sepas exactamente qué tocar primero.
Errores de esquema: RSC-005
RSC-005 es el error más habitual, y el que más asusta. Significa que un archivo falló la validación de esquema contra la spec — el XML está bien formado, pero algo en él no está permitido donde lo pusiste. Causas frecuentes: un atributo que no corresponde a un elemento, un elemento anidado dentro de otro que no puede contenerlo, un valor fuera de la lista permitida, o una propiedad indebida en un itemref del spine.
El texto después del código es la instrucción real — léelo literalmente. Un mensaje como “attribute X not allowed here” te dice con precisión qué atributo quitar o mover. Los arreglos casi siempre son locales: borra el atributo problemático, reanida el elemento o corrige el valor. Arregla uno, vuelve a ejecutar, y un número sorprendente de líneas RSC-005 suele reducirse a una sola causa repetida entre capítulos.
Recursos que faltan y recursos remotos
RSC-007 y RSC-001 significan que epubcheck siguió una referencia — una hoja de estilos, imagen, fuente o una entrada del spine — y no encontró el destino dentro del contenedor. La causa casi siempre es una discrepancia de ruta o de mayúsculas: un href apunta a images/Cover.jpg pero el archivo es images/cover.jpg, o un archivo se renombró y su referencia no. Las rutas de EPUB distinguen mayúsculas; corrige la ruta o restaura el archivo que falta.
RSC-006 marca un recurso remoto — una URL que apunta fuera del EPUB. La spec solo permite referencias remotas para un conjunto reducido de medios, como audio y video; todo lo demás, incluidas imágenes, fuentes y hojas de estilo, debe ir empaquetado dentro del contenedor. El arreglo es descargar el recurso, añadirlo al manifest y reapuntar la referencia a la copia local.
El documento de paquete: errores OPF
Los errores OPF-* vienen del documento de paquete .opf — el manifest, la metadata y el spine. Los más frecuentes: un archivo que existe en el contenedor pero no está declarado en el manifest (o está declarado pero falta), un spine que referencia un id sin item correspondiente en el manifest, o metadata Dublin Core requerida ausente o mal formada, como un dc:identifier, dc:title o dc:language faltante.
Trata el OPF como la fuente de verdad: cada archivo de contenido debe aparecer una vez en el manifest con el media type correcto, y cada itemref del spine debe apuntar a un id de manifest existente. Añade la declaración que falta, corrige el media type o proporciona el valor de metadata requerido, y la cascada de errores derivados suele resolverse con ello.
Marcado, navegación y empaquetado
Los errores HTM-* significan que el propio XHTML está mal formado o usa algo que la spec no permite — una etiqueta sin cerrar, un namespace no declarado o una construcción obsoleta. Como el contenido EPUB es XHTML, debe ser XML bien formado: cada etiqueta cerrada, cada atributo entre comillas. Los errores de NCX y navegación apuntan a la tabla de contenidos — un enlace roto en el documento nav, o un desajuste entre el nav y el orden del spine.
Los errores PKG-* tienen que ver con cómo se ensambla el ZIP. El clásico: el archivo mimetype debe ser la primera entrada del archivo y estar guardado sin comprimir, sin bytes extra. Si tu herramienta de compresión lo comprimió o reordenó las entradas, epubcheck se queja antes incluso de leer el contenido. Vuelve a empaquetar con el mimetype primero y sin comprimir — la mayoría de las herramientas de exportación EPUB lo hacen solas, así que esto suele significar evitar un re-zip manual.
La solución, paso a paso
-
1
Valida y lee el reporte en crudo
Pasa tu EPUB por epubcheck 5.x y captura la salida completa. Cada línea trae un código, una severidad y una ubicación de archivo y línea — ese trío es tu mapa al punto exacto que hay que cambiar. No adivines; el reporte ya nombra el archivo.
-
2
Ordena por severidad, primero los bloqueantes
Separa los errores de los warnings. Los errores rompen la conformidad y pueden impedir que los lectores abran el libro, así que resuelve cada uno antes de tocar un solo warning. Los warnings son de aviso y pueden esperar a que los errores desaparezcan.
-
3
Arregla por familia, del contenedor hacia adentro
Agrupa los hallazgos — esquema, recursos, documento de paquete, marcado — y empieza por el contenedor: primero mimetype y empaquetado, luego el OPF, y después los archivos de contenido. Arreglar una causa raíz suele resolver varias líneas de golpe.
-
4
Vuelve a validar hasta que el reporte esté limpio
Ejecuta epubcheck de nuevo tras cada tanda de arreglos. Los códigos encadenan, así que una corrección puede resolver o revelar otras. Repite hasta que no quede ningún error, y luego decide qué warnings vale la pena limpiar para tus lectores.