Possible replacement for EPUBCHECK

[JSWolf]

I've found yet some more differences between epubveri and epubcheck.

I change ePub type from 2 to 3 and then got these.

Here is the OPF.

<?xml version='1.0' encoding='utf-8'?>
<package xmlns="http://www.idpf.org/2007/opf" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="bookid">
  <metadata>
    <dc:identifier id="bookid">urn:asin:B0DWKRJQSH</dc:identifier>
    <dc:title>The Metal Woman</dc:title>
    <dc:creator opf:role="aut">Frank J. Cavill</dc:creator>
    <dc:language>en</dc:language>
    <dc:publisher>Pedro Urvi</dc:publisher>
    <dc:date opf:event="publication">2025-04-24</dc:date>
    <meta name="cover" content="image_rsrc51H.jpg"/>
  </metadata>
  <manifest>
    <item href="cover.xhtml" id="c0.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter07.xhtml" id="c136.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter08.xhtml" id="c179.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter09.xhtml" id="c1A1.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter10.xhtml" id="c1F2.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter11.xhtml" id="c1ME.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter12.xhtml" id="c1T5.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter13.xhtml" id="c1X3.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter14.xhtml" id="c210.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter15.xhtml" id="c25D.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter16.xhtml" id="c29F.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter17.xhtml" id="c2DR.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter18.xhtml" id="c2J8.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter19.xhtml" id="c2R4.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter20.xhtml" id="c2X6.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter21.xhtml" id="c322.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter22.xhtml" id="c32S.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter23.xhtml" id="c36R.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter24.xhtml" id="c3AE.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter25.xhtml" id="c3DV.xhtml" media-type="application/xhtml+xml"/>
    <item href="prologue.xhtml" id="c3F.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter26.xhtml" id="c3HU.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter27.xhtml" id="c3PH.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter28.xhtml" id="c3XR.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter29.xhtml" id="c42T.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter30.xhtml" id="c461.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter31.xhtml" id="c4A0.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter32.xhtml" id="c4F0.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter33.xhtml" id="c4M0.xhtml" media-type="application/xhtml+xml"/>
    <item href="acknowledgements.xhtml" id="c4VE.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter01.xhtml" id="c5T.xhtml" media-type="application/xhtml+xml"/>
    <item href="titlepage.xhtml" id="c9.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter02.xhtml" id="cBP.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter03.xhtml" id="cGJ.xhtml" media-type="application/xhtml+xml"/>
    <item href="copyright.xhtml" id="cM.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter04.xhtml" id="cMY.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter05.xhtml" id="cSP.xhtml" media-type="application/xhtml+xml"/>
    <item href="chapter06.xhtml" id="cY4.xhtml" media-type="application/xhtml+xml"/>
    <item href="cover.jpg" id="image_rsrc51H.jpg" media-type="image/jpeg"/>
    <item href="stylesheet.css" id="stylesheet.css" media-type="text/css"/>
    <item href="toc.ncx" id="toc.ncx" media-type="application/x-dtbncx+xml"/>
  </manifest>
  <spine toc="toc.ncx">
    <itemref idref="c0.xhtml"/>
    <itemref idref="c9.xhtml"/>
    <itemref idref="cM.xhtml"/>
    <itemref idref="c3F.xhtml"/>
    <itemref idref="c5T.xhtml"/>
    <itemref idref="cBP.xhtml"/>
    <itemref idref="cGJ.xhtml"/>
    <itemref idref="cMY.xhtml"/>
    <itemref idref="cSP.xhtml"/>
    <itemref idref="cY4.xhtml"/>
    <itemref idref="c136.xhtml"/>
    <itemref idref="c179.xhtml"/>
    <itemref idref="c1A1.xhtml"/>
    <itemref idref="c1F2.xhtml"/>
    <itemref idref="c1ME.xhtml"/>
    <itemref idref="c1T5.xhtml"/>
    <itemref idref="c1X3.xhtml"/>
    <itemref idref="c210.xhtml"/>
    <itemref idref="c25D.xhtml"/>
    <itemref idref="c29F.xhtml"/>
    <itemref idref="c2DR.xhtml"/>
    <itemref idref="c2J8.xhtml"/>
    <itemref idref="c2R4.xhtml"/>
    <itemref idref="c2X6.xhtml"/>
    <itemref idref="c322.xhtml"/>
    <itemref idref="c32S.xhtml"/>
    <itemref idref="c36R.xhtml"/>
    <itemref idref="c3AE.xhtml"/>
    <itemref idref="c3DV.xhtml"/>
    <itemref idref="c3HU.xhtml"/>
    <itemref idref="c3PH.xhtml"/>
    <itemref idref="c3XR.xhtml"/>
    <itemref idref="c42T.xhtml"/>
    <itemref idref="c461.xhtml"/>
    <itemref idref="c4A0.xhtml"/>
    <itemref idref="c4F0.xhtml"/>
    <itemref idref="c4M0.xhtml"/>
    <itemref idref="c4VE.xhtml"/>
  </spine>
  <guide>
    <reference type="start" title="Start" href="cover.xhtml"/>
  </guide>
</package>

epubveri output:

OEBPS/content.opf	9	14	ERROR RSC-005: attribute "opf:event" is not allowed here
OEBPS/content.opf	6	17	ERROR RSC-005: attribute "opf:role" is not allowed here
OEBPS/content.opf	13	3	ERROR RSC-005: EPUB 3 requires a navigation document (a manifest item with properties="nav")

epubcheck output:

content.opf Line:13 Col:13 ERROR(RSC-005): Error while parsing file: Exactly one manifest item must declare the "nav" property (number of "nav" items: 0).
content.opf Line:9 Col:38 ERROR(RSC-005): Error while parsing file: attribute "opf:event" not allowed here; expected attribute "id"
content.opf Line:6 Col:32 ERROR(RSC-005): Error while parsing file: attribute "opf:role" not allowed here; expected attribute "dir", "id" or "xml:lang"

Now changing back to ePub 2, I got the following differences.

epubveri output:

OEBPS/content.opf	11	5	ERROR RSC-005: element "meta" is missing a required attribute
OEBPS/content.opf	11	11	ERROR RSC-005: attribute "property" is not allowed here

epubcheck output:

content.opf Line:11 Col:63 ERROR(RSC-005): Error while parsing file: attribute "property" not allowed here; expected attribute "content", "id", "name", "scheme" or "xml:lang"
content.opf Line:11 Col:63 ERROR(RSC-005): Error while parsing file: element "meta" missing required attributes "content" and "name"
content.opf Line:11 Col:83 ERROR(RSC-005): Error while parsing file: text not allowed here; expected the element end-tag

[Kayadelenium]

Thanks for this. I rebuilt both books from your OPF and ran the two tools side by side.

The short answer first, because I'd rather say it plainly than bury it: in both cases we report the same errors as epubcheck, with the same IDs on the same lines, and the same number of them. Nothing is missed and nothing is invented. What differs is the column and the wording — and one of those was worth fixing.

The message that didn't say enough. You're right that this is close to useless:

element "meta" is missing a required attribute

epubcheck names them, and now so do we:

element "meta" is missing required attributes "content" and "name"

The commonest case isn't meta at all — it's an img with no alt. On my 405-book test library that message occurs 3,434 times, and until now not one of them mentioned alt. It also means a tool reading our JSON can act on the finding instead of parsing English. Both are in the next release.

The third epubcheck line in your EPUB 2 output. "text not allowed here" — we do implement that one. What you're seeing is deliberate: once an element has already failed on its attributes, we don't go on to report its content as well. Give the same meta valid attributes and stray text and we report it:

ERROR RSC-005: stray text is not allowed directly in "meta"; wrap it in an element

So epubcheck reports both, we report the first. Our RSC-005 count is lower than epubcheck's on purpose, so one mistake reads as one problem. If you'd rather see every consequence of a defect listed, that's a fair argument and I'd like to hear it — it's a choice, not a limitation.

The columns. We point at where a construct starts, epubcheck at where it ends. For opf:role on line 6 we say column 17, where the attribute begins; epubcheck says 32, just past it. Same for the nav one — line 12 either way, column 3 against 13. Neither is wrong, and ours is the position an editor would put a cursor at. I'm not planning to change it, but you were diffing columns, so you should know it's a decision rather than an accident.

The nav wording differs too — we say a navigation document is required, epubcheck says exactly one manifest item must declare the "nav" property. Same ID, same line, same defect, and I think both are clear enough to leave alone.

One caveat on all of the above: your manifest and spine were elided in the post, so I rebuilt them minimally. If the real file produces anything beyond the lines you quoted, send it and I'll look at the actual book rather than my reconstruction.

[JSWolf]

All the errors were just in the OPF. No other errors outside of the OPF.

[Kayadelenium]

epubveri 0.13.0 is out.

This release is almost entirely false positives — twenty-six of them.

Twenty-three are the same shape: one defect reported twice. Each message was true, but the count did not match epubcheck's, and to anyone running both tools side by side that is indistinguishable from an invented error. Most were a hand-written check of mine saying what a schema had already said — a missing <spine>, a manifest <item> with no media-type, a duplicate manifest id, nested <dfn>, and so on.

Three were invented errors outright, and these are the ones that could reach a real book:

- <iframe srcdoc> was rejected. It is valid, and five more HTML5 iframe attributes were missing along with it: loading, sandbox, allowfullscreen, allow, referrerpolicy.
- Seventeen printable ASCII characters in a hostname were errors — a comma, and ! $ & ' ( ) * + ; = ~ ^ | { } and a backtick. epubcheck accepts all of them. (The comma is the one epubcheck's own corpus names, in issue #1034: it records that it should probably flag it, and does not. Reporting it anyway was my divergence, not a finding.)
- A media overlay whose stylesheet simply does not define the active-class was reported. epubcheck only reports when the document has no CSS at all.

Honest scope: exactly one of the twenty-six moves a book on my own shelf of 405 (the Adobe page-map one). The rest are visible only if you diff the two tools. They were found by running epubcheck over its own test fixtures and comparing the two reports line by line instead of by id — the id-set diff is blind to every one of them, because the extra finding carries the same id at the same severity. Comparing counts rather than id sets has now produced thirty-five findings in two days, two of them things I was missing rather than inventing.

There is one breaking change, but it is Rust-library-only (an enum variant now carries the names of the attributes an element is missing). The CLI, the JSON output and the WASM package are unchanged, so the Sigil plugin and anything parsing the JSON needs no update.

Downloads (8 platforms): https://github.com/veripublica/epubv...es/tag/v0.13.0
Full changelog: https://github.com/veripublica/epubv...n/CHANGELOG.md

As always, reports of a wrong error on a valid book are the most useful thing anyone can send me.

[JSWolf]

Another difference. The difference is in the line and column.

Here is the relevant OPF code.

</spine>
<guide>
</guide>
</package>

Here is the epubcheck output

package.opf Line:164 Col:9 ERROR(RSC-005): Error while parsing file: element "guide" incomplete; missing required element "reference"

here is the epubveri output

OEBPS/package.opf	163	1	ERROR RSC-005: element "guide" has incomplete content; missing required element "reference"

[Kayadelenium]

Good catch, and thank you for the precise report — both numbers are correct. We are pointing at two different things, and it is on purpose. Let me explain it plainly, because it is not obvious from the output.

Your file has:

163: <guide>
164: </guide>

epubcheck says 164:9. That is the character right after </guide>.
epubveri says 163:1. That is the <guide> itself.

Why epubcheck lands there: it reads the file from top to bottom, one tag at a time, and reports the spot it had reached when the problem became apparent. A "this element is missing something inside it" problem cannot become apparent until the closing tag arrives — until then, the missing thing might still be coming. So it reports at </guide>, because that is where it found out.

Why we land where we do: we load the whole file first, so we can point at the element that is actually wrong rather than at the moment of discovery. To fix an empty <guide> you go to the <guide>. That is the line we give you.

If you want the evidence that epubcheck's position is a side effect of how it reads rather than a deliberate choice, it uses three different anchors for three kinds of problem. I measured each one on its own small book:

- element X not allowed → just after X's opening tag
- element X incomplete → just after X's closing tag (your case)
- a bad attribute → just after the > of the opening tag, which points at neither the element nor the attribute it is complaining about

All three are simply "wherever the cursor was". The same thing explains something else you may have noticed: when epubcheck rejects an element it repeats that same message once for every child inside it. On one real book here, 80 <article> elements produced 1887 messages.

There is a practical reason too. epubsana, the repair tool, uses these positions to go and fix the fault. Given the closing tag it would have to search backwards, and with nested elements it could not reliably tell which opening tag the position belonged to.

So I am going to leave this one as it is — not because matching would be hard (it is about two lines of code) but because I think the start of the problem is the more useful place to be sent. If that ever gets in your way in practice rather than in a diff, tell me and I will look again.

[JSWolf]

Neither way gets in my way, So I'm OK with your way for epubveri now that I know the reasoning behind it. Thanks.

[Kayadelenium]

epubveri 0.13.1 is out.

Let me be honest about what this one is: mostly parity work that will not change what you see. Seven false positives were fixed, and I checked every one against my local shelf of 415 real books — not one of them changes any of those books. They were all wrong only against epubcheck's own test fixtures. What a reader actually gains is three true findings on two books, each confirmed against epubcheck at the same file, same line, same wording.

The substantial part is SVG in EPUB 2 books.

epubcheck validates inline and standalone SVG in an EPUB 2 publication against the full SVG 1.1 grammar, normatively — errors, not warnings. We were doing a fraction of that. Now the whole of it is there: which elements exist, which attributes exist, what may contain what, which attributes are required, and which attribute values are constrained.

Three things I found while doing it that are worth knowing:

- Two of our checks were gated to EPUB 3 on the reasoning that "epubcheck has no opinion in EPUB 2". It has one, and a stricter one. The comment's own example was a lowercase viewbox in a real book, written off as our false positive. epubcheck reports it as an error.
- Every list I added was diffed against epubcheck's own schema before being switched on: all 81 SVG element names and all 256 attribute names it declares were already in ours, so the new checks could not invent a finding it does not also make.
- The attribute value rules turned out to be almost nothing. epubcheck declares 22 SVG datatypes and 17 of them constrain nothing at all — width="abc", r="-1", opacity="junk", a broken path, all clean there. So they are clean here too. Five attributes are genuinely constrained and those are now checked. I am not adding errors epubcheck does not make.

Cost of all that on real books: my 415-book shelf gained nothing from the SVG work, and 260 of those books do carry inline SVG. Your mileage may differ, and that is exactly the report I would like to get.

Also in this release, and thanks to JSWolf for raising it: the line/column difference on an empty <guide> is now documented as a deliberate choice rather than left to be rediscovered.

Downloads (8 platforms): https://github.com/veripublica/epubv...es/tag/v0.13.1
Full changelog: https://github.com/veripublica/epubv...n/CHANGELOG.md

As always — a wrong error on a valid book is the most useful thing you can send me.

[JSWolf]

I think this is an error. It counts to the cover html file but mentions the error is in the OPF. Also, it point to the cover html instead of the line in the OPF where the property needs to be added.

epubveri reports:

OEBPS/Text/cover_page.xhtml	3	1	ERROR OPF-014: content document uses svg but doesn't declare the "svg" property

epubcheck reports:

cover_page.xhtml Line:-1 Col:-1 ERROR(OPF-014): The property "svg" should be declared in the OPF file.

But again that's not where the error is.

The cover HTML is just a box standard SVG wrapper for a JPG image. The eBook is ePub3.

[Kayadelenium]

epubveri 0.13.2 is out. The fix worth knowing about is one that affects real books: an EPUB 2 book using HTML5 elements got errors from epubveri that epubcheck does not give.

Take a section, figure, nav or article element in a book declared version="2.0". Those elements don't exist in EPUB 2's grammar, so both tools reject them — correctly. But epubcheck reports the element and stops, while epubveri went on to report the element's contents as well, against a content model they were never in the scope of. A figure would draw an error, and then so would its figcaption, its img, and any i or br inside it.

On one book in my test shelf epubcheck names "figure" and nothing else; epubveri named it 57 times and then added 59 errors epubcheck never makes. Across my 415-book shelf the fix removes 1,878 wrong errors from 9 books:

Nutuk                     3114 -> 2358
Linear Algebra            3362 -> 2737
Yaşam ve Ölüm Yorgunu      803 ->  420
Ekonomi Politikası         231 ->  172
(and five others, smaller)

Every book I checked now names exactly the same set of elements epubcheck does. This had been in there a long while, so if you have run an EPUB 2 conversion through epubveri and found the error list longer than it should be, it is worth running again.

JSWolf, your OPF-014 report (post #264) is in this release. You were right that the message talked about the OPF while pointing at the XHTML. The finding now points at the svg element that actually requires the property, instead of at html — on a Calibre cover wrapper that moves it from line 1 to line 13 — and the message says where the fix goes: "add it to this document's manifest item in the OPF". The file path still names the content document, because that is what epubcheck names and what tells you which document is being talked about.

Seven more wrong errors are fixed, none of which had reached anyone. I ran both tools over epubcheck's own 981-book test corpus and diffed them, then probed every disagreement one book at a time. Among them: a remote CSS @import drew an error from epubveri that told you to declare a property which cannot legalise it; and the EPUB 3 package rules were being applied to EPUB 2 books that happened to carry an EPUB 3 attribute.

Some missing findings closed too — a video poster or an object's data attribute pointing at a file that isn't in the book drew nothing from epubveri before, and a standalone SVG's #fragment references are now resolved.

Downloads (8 platforms, no JVM needed):
https://github.com/veripublica/epubv...es/tag/v0.13.2
Full notes: https://github.com/veripublica/epubv...n/CHANGELOG.md

JSWolf — one thing still open from your earlier request, a warning for unused images. I measured it, and the request turns out to be a different question than it looks:

For EPUB 3 this check already exists in both tools — epubcheck and epubveri both emit OPF-097, "declared in the manifest, but no content document references it". For EPUB 2, neither tool says anything. You validate EPUB 2 books and Doitsu was looking at EPUB 3, so you were both right about different books.

The real question is therefore whether OPF-097's question should be asked of an EPUB 2 book at all. That would be epubveri reporting something epubcheck doesn't, so it would go behind the opt-in --advisory flag rather than into the normal output — I don't want the two tools disagreeing on whether a book passes.

Worth doing? And is it images specifically, or any unreferenced resource?