Possible replacement for EPUBCHECK

[Kayadelenium]

@JSWolf — your point in #192 is what I spent the rest of today on, so here is what came of it.

Some context first, because it is the reason this is worth doing at all: epubcheck's last release was 5.3.0 on 1 September 2025, and its main branch has had exactly one commit since — a CI configuration change. There are 104 open issues, and a good number are marked accepted or ready for implementation, meaning a maintainer has already decided they are right. That is a year of decided-but-unimplemented work in the tracker.

I read the 60 newest issues today. Two of them turned out to be defects epubveri shared with epubcheck, and both are fixed in 0.9.25:

- <meta property="a11y:contactEmail"> — valid accessibility metadata, and both tools reported it as an undefined property. EPUB Accessibility 1.2 added it on 4 September 2025, three days after 5.3.0 shipped, so that release cannot know it. I had no such excuse: my vocabulary list was copied from 1.1. (their issue #1669, reported by Gregorio Pellegrino, unanswered since July)
- A resource referenced from <video> — its own src or a child <source> — was reported as a foreign resource needing a manifest fallback. EPUB 3.3 exempts "all video codecs referenced from the HTML video, including any child source elements", unconditionally. Both tools were instead testing for a video/ media type prefix, so an HTTP-live-streaming playlist, which plays straight from the element and can carry no fallback at all, was rejected. Audio stays restrictive, as the same section requires — I measured the boundary four ways. (their issue #1662, opened by the EPUB spec editor)

Both of those are cases where epubveri now accepts something epubcheck still rejects. That direction is deliberate and it is the only direction I will move in ahead of them: being wrong that way costs a missed error, which harms nobody who has it. Reporting something epubcheck does not is the opposite — it looks exactly like a false positive to anyone comparing the two outputs, and that is what --advisory exists for.

One more thing from the same read that may be practically useful here, since I believe @DNSB ran into it recently: epubcheck's JSON and XML output caps the locations listed per message at 25 (MAX_LOCATIONS in CheckMessage.java), with the rest summarised as additionalLocations. Three separate people have open issues about it — #1666, #1611 and #1489, the oldest from 2023. If you have ever fixed the files a message named, re-run, and been surprised to see the same message name new files, that is why. epubveri has no such cap.

Where my reading of one of their issues looks useful to them rather than only to me, I intend to take it back to their tracker rather than leave it here — I have filed there before and will again.

Nothing here is a complaint about epubcheck. It is a considerably larger program than mine, it is the reference implementation, and two of the three things above are defects I had too — I only found them by reading their tracker.

[Kayadelenium]

Originally Posted by JSWolf

I've found what I think may be an error in epubveri and epubcheck as both do not report this as an error. the last two entries in the NCX ToC have the same source and the same playorder. I don't think this is allowed. I'm not sure about the duplicate source, but the playorder should not be duplicated.

    <navPoint id="num_35" playOrder="34">
      <navLabel>
        <text>32 The snow - covered pass</text>
      </navLabel>
      <content src="chapter33.xhtml"/>
    </navPoint>
    <navPoint id="num_34" playOrder="34">
      <navLabel>
        <text>33 The cult of the Gaal - El</text>
      </navLabel>
      <content src="chapter33.xhtml"/>
    </navPoint>
  </navMap>
</ncx>

@JSWolf — I checked this one properly, and the short answer is that epubveri and epubcheck are both right to stay silent, but your instinct that something is wrong with that book is also right. It just isn't the playOrder.

The duplicate playOrder is required here. epubcheck's NCX Schematron has two rules that work as a pair:

ncx_playOrderMatch2 — elements with identical playOrder values must point to the same target
ncx_playOrderMatch — elements that point to the same target must have identical playOrder values

Together they make playOrder↔target a one-to-one correspondence. Your two navPoints both point at chapter33.xhtml, so the second rule obliges them to carry the same playOrder. If you "fixed" the duplicate by giving one of them playOrder="35", you would turn a valid NCX into an invalid one.

I measured the boundary to be sure. Same playOrder, different targets, and both tools report it — four findings each, identical messages and positions:

ERROR(RSC-005): identical playOrder values for navPoint/navTarget/pageTarget that do not refer to same target
ERROR(RSC-005): different playOrder values for navPoint/navTarget/pageTarget that refer to same target

So the rules are working; the real defect is one level up. Two different chapters are pointing at the same file. "32 The snow-covered pass" and "33 The cult of the Gaal-El" both land on chapter33.xhtml, so one of them — almost certainly the first — has the wrong src. Your ids say the same thing: num_35 and num_34, in that order, both on playOrder="34". Something in whatever produced that TOC collapsed two entries onto one file, and the duplicate playOrder is the symptom the NCX rules then forced into existence.

I looked at whether this is worth flagging as an advisory, since no validator catches it. Across 347 NCX files in my test corpus, 6 books have two entries pointing at the same file with no fragment. Three are genuine defects of exactly your kind — "XXXVIII" and "XXXIX" both on chapter38.xhtml in one book, two authors' biographies both on biography-author1.xhtml in another. The other three are legitimate: a part heading and its first chapter living in one file, an omnibus listing each volume's title page twice.

Half right is not good enough for a check that would run on everyone's books, and nothing in the markup separates the two cases — so I'm not adding it. But it is a real class of defect, and if you have a producer that does this systematically, the thing to grep for is two <content src> values that are identical with no #fragment.

Thanks for posting the snippet rather than just the symptom — the ids are what made the diagnosis obvious.

[JSWolf]

I tested a different variations in id, playorder, and source. The one i posted is the one that came up with no error even though it is an error. Neither program flagged it.

Personally, I would like epubvari to flag it. I would like epubvari to flag everything that's wrong even if epubcheck doesn't.

One thing I've noticed through the years is the biggest issue with a lot of Readers is eBooks with errors. So it would be good to make sure all errors are caught when possible.

[Kayadelenium]

epubveri 0.9.26 — two changes, both from posts in this thread.

A check I was missing on NCX links. If a book's files have spaces in their names — Kamelyali Kadin_split_000.html — epubcheck reports one error per manifest entry and one per <navPoint> pointing at them. I was only doing the manifest half: 32 findings where epubcheck gives 60. They now agree on all 60. Three of the 375 real books I test against were affected.

A new advisory, ADV-009.

@JSWolf — this one is yours, and the answer to your duplicate playOrder is that epubcheck and epubveri are both right to stay silent, while your instinct that the book is broken is also right. The duplicate is required: epubcheck's NCX rules work as a pair, and two entries pointing at the same target must carry the same playOrder. Giving one of them a different number would turn a valid NCX into an invalid one.

The real defect is one level up — two chapters pointing at the same file — and nothing catches it. Now --advisory does.

Getting there took two corrections I should own. I first measured the idea and rejected it as too noisy, having counted books rather than findings, which made the comparison meaningless. Then I checked whether nesting tells the good cases from the bad and concluded it doesn't. It does, and obviously in hindsight: a part heading sharing a file with its first chapter is a parent pointing at its child's document, and the format gives it nowhere else to point, since <content> is mandatory in a navPoint. Only sibling pairs are worth flagging.

On 375 books that is 4 findings, 3 of them real — a chapter, a second author's biography and a diagram, each unreachable from its table of contents. The fourth is a book where Calibre listed the title page twice. It never touches the verdict or the exit code.

@Doitsu — on marking the findings epubsana could repair: I measured it rather than guessing. Across those same 375 books, 50,229 findings carry a rule identifier and 87% of them match a fixer epubsana already has. So the idea is well founded.

I still don't think the marker belongs in epubveri, for one reason: it would be epubveri asserting a fact about another program's current abilities, on somebody else's release schedule. The day epubsana gains or drops a fixer my label quietly becomes a lie, and a "repairable" flag that is wrong is worse than no flag. epubsana knows exactly what it can fix, and always will.

So before I build anything — when you see that marker, what do you do next? If the answer is "I run epubsana", then it can tell you itself and more accurately. If it's something else, like deciding whether a book is worth opening at all, that's a different feature and I'd rather build the right one.

[Doitsu]

Originally Posted by Kayadelenium

So before I build anything — when you see that marker, what do you do next? If the answer is "I run epubsana"...

I have both the epubveri and epubsana plugins, but I usually run only epubveri. If it reported something like, "epubveri found one or more issues that epubsana can fix," I would know that running epubsana is worthwhile.

[JSWolf]

Originally Posted by Doitsu

I have both the epubveri and epubsana plugins, but I usually run only epubveri. If it reported something like, "epubveri found one or more issues that epubsana can fix," I would know that running epubsana is worthwhile.

Where can I find an ebubveri plugin for calibre? Thanks.

[KevinH]

@Doitsu

And if you have modfied your epubcheck plugin (for Sigil or Calibre) to create an epubveri plugin, and if it can update itself after every epubveri release (because epubveri dev is moving so fast), it would certainly help get epubveri in the hands of more Sigil and Calibre users which should help generate more testing.

And fwiw, if you do not have time to create one for Sigil, I would be happy to take a shot at it based on your current epubcheck plugin. Just let me know if you would prefer that approach.

Once tested and robust maybe Sigil and Calibre epubveri and epubsana plugins could be built into epubveri's github ci and release processes if they are at all interested.

[Doitsu]

Originally Posted by KevinH

And if you have modfied your epubcheck plugin (for Sigil or Calibre) to create an epubveri plugin, and if it can update itself after every epubveri release (because epubveri dev is moving so fast), it would certainly help get epubveri in the hands of more Sigil and Calibre users which should help generate more testing.

I've uploaded a quick & dirty Sigil epubveri plugin to the Sigil forum. I'll upload a similar Calibre plugin later.

[KevinH]

Thank you! I will add it to the Sigil Plugin Index later tonight when I get back home.

Update: epubveri is now in the Sigil Plugin Index.

https://www.mobileread.com/forums/sh...d.php?t=374939

[JSWolf]

Originally Posted by Doitsu

I've uploaded a quick & dirty Sigil epubveri plugin to the Sigil forum. I'll upload a similar Calibre plugin later.

Thank you.

[JSWolf]

Why is @font-face CSS-028 being flagged when it's correct?

@font-face {
  font-family: Display;
  font-weight: normal;
  font-style: normal;
  src: url(font_rsrcEU.ttf);
}

[PeterT]

Originally Posted by Doitsu

I've uploaded a quick & dirty Sigil epubveri plugin to the Sigil forum. I'll upload a similar Calibre plugin later.

I've had this plugin for a few weeks now, running on a Chromebook with Sigil in an App image, have experienced zero issues with it (and numerous succesful epubveri upgrades) updates.

[Doitsu]

Originally Posted by JSWolf

Why is @font-face CSS-028 being flagged when it's correct?

That's a USAGE message, not an error. EPUBCheck displays the same message when USAGE mode is enabled.

I.e., epubveri mirrors the behavior of EPUBCheck.

[JSWolf]

Originally Posted by Doitsu

That's a USAGE message, not an error. EPUBCheck displays the same message when USAGE mode is enabled.

I.e., epubveri mirrors the behavior of EPUBCheck.

What's the point of it? IMHO, there is no point. It looks like an error message. It really should not be showing a place in the eBook that's correct.

[Kayadelenium]

epubveri 0.9.27 and 0.9.28 — two releases, and one of them fixes something you may have noticed.

Findings came out in a different order every time you ran it. Same book, same binary, same findings — shuffled. It affected 94 of the 385 real books I test against, and none of my four instruments could see it, because they all compare which messages appear, not what order they arrive in. It surfaced by accident while I was verifying an unrelated change: I compared two runs byte-for-byte, the comparison failed, and so did the control. Fixed in 0.9.27; three full runs over 385 books are now byte-identical.

If you ever diffed two epubveri runs and got noise, that was this, and I'm sorry.

@Doitsu — one change affects your plugin, and it is deliberately early. The four EPUB 3.4 advisories are renamed: ADV-005…008 are now NEXT-005…008. Nothing else moves — same checks, same messages, same severity, same flag.

The reason for a separate family is that --advisory was carrying two different claims under one prefix. NEXT-* means a published spec requires this and epubcheck hasn't implemented it yet, so it becomes a real error the day epubcheck catches up. ADV-* means no spec says anything, but the book is still wrong — those never become errors. If a plugin wants to present those differently, code.startswith("NEXT-") is now all it takes; the JSON also carries data.advisory_basis as spec-ahead or spec-silent.

I did this now specifically because your plugin is new and nothing else consumes those codes yet. A published ID gets more expensive to move every week.

@PeterT — thank you for the Chromebook report. Knowing the plugin's self-update path works on something other than my machine is worth more than it probably felt like to write.

@JSWolf, on CSS-028 — Doitsu's answer in #208 is correct, and your objection in #209 is still a fair one, so let me give you the part that's actually asymmetric.

CSS-028 is a USAGE message in both tools; it says "this book uses @font-face", not "this is wrong". But epubcheck hides usage messages unless you pass -u, and epubveri shows them by default. So the message isn't new — what's new is that you can see it. That's my choice, not epubcheck's, and you're the second person it has confused.

You're right that a line pointing at correct markup, formatted like every error line, reads as a complaint. I'd rather fix that than defend it. The obvious options are to hide usage by default and add a flag to show it (matching epubcheck), or to keep showing it but stop making it look like a finding.

Which would you rather have? Anyone with an opinion, now is a good moment — it's a default, and defaults are hard to change later.

Also in these two releases: a URL check that was too narrow now matches epubcheck exactly; the README finally explains why there are two tools and what epubsana is for; and both tools were timed on the same 20 books — epubcheck 2013 ms/book, epubveri 191 ms/book. About ten times faster, same verdict. Worth saying precisely because the obvious guess is wrong: JVM startup is only about 70 ms of epubcheck's 2013. It isn't a slow launch, it's the validation work.