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.