Possible replacement for EPUBCHECK

[Kayadelenium]

epubveri 0.9.18 is out — four false positives, all found here rather than reported.

The one to upgrade for: a manifest item declared text/html in an EPUB 2 book. Calibre emits these. We treated them as foreign resources, so one real book drew 91 bogus OPF-043 plus a handful of RSC-010/OPF-032. epubcheck warns once (OPF-035) and carries on validating the document — now so do we.

That one cuts both ways: those documents were never being checked at all, so a book of yours may now show new errors that are real — broken links inside them were silently skipped before.

Also fixed:
- A valid TIFF named .png was reported as a corrupt image. It's a wrong extension (PKG-022), not corruption.
- Two extra RSC-005 on ARIA id references — one in EPUB 2, where epubcheck checks nothing, and one duplicate in EPUB*3.

Binaries: github.com/veripublica/epubveri/releases/tag/v0.9.18
Browser demo: veripublica.github.io/epubveri

As always — if our output disagrees with epubcheck's on one of your books, both logs as plain text is the most useful thing you can send.

[Doitsu]

@Kayadeleniu:

I noticed that there still discrepancies between epubveri and EPUBCheck for DNSB's second scrambled book.

epubveri does not flag epub2-only metadata attributes with an opf prefix. For example:

<dc:identifier opf:scheme="calibre">urn:uuid:33f269c3-cb0c-4cab-b952-526cf2a8cad3</dc:identifier>

I also have a suggestion:

Since you apparently develop epuveri and epubsana in parallel, IMHO, it'd be helpful if epuberi displayed an ADV message whenever it finds an issue that epubsana can fix.

[Kayadelenium]

epubveri 0.9.19

New release: https://github.com/veripublica/epubv...es/tag/v0.9.19

Doitsu — the report from page 13 is fixed. Thank you for sending epubcheck's output next to ours; that pair of files turned this into a twenty-minute diagnosis instead of a guess. The book drew 13 findings from epubcheck and 7 from epubveri, and all six we missed were the same thing: a book converted from EPUB 2 keeps opf:role, opf:file-as and opf:scheme on its Dublin Core elements, and EPUB 3 replaced all of those with <meta refines>.

The cause turned out to be worse than a missing rule. epubveri's model of an EPUB 3 <metadata> element was completely permissive, so no attribute on any metadata element was being checked at all — it was a missing question rather than a wrong answer. That surface now follows the EPUB 3 package schema, including the part that is easy to get wrong: xml:lang is valid on dc:title and an error on dc:language, because those two elements take different attribute lists.

Five more EPUB 2 rules where XHTML 1.1 is stricter than HTML5 and epubveri was too permissive: ol@start, ol@type, li@value, data-* attributes, and an empty <tr> or row group. They all come from modules that OPS 2.0.1 does not include — the same reason align and clear are already errors.

And one in the other direction, which matters more: epubveri was reporting CSS-001 (direction / unicode-bidi) on EPUB 2 books. epubcheck applies that rule only to EPUB 3, so this was a real false positive on valid EPUB 2 markup. Fixed.

Where the numbers come from, for anyone who wants to judge them: on epubcheck's own test corpus, 606 of 607 expected message IDs match exactly, with no false positives across 355 should-be-clean cases. On a local corpus of 346 real books cross-checked against epubcheck 5.3.0, 339 agree on the reported ID set exactly, and there is no ID that epubveri reports and epubcheck does not. The remaining differences are all in the other direction — things epubcheck catches and epubveri still misses.

Downloads for 8 platforms are on the release page; the Linux musl builds need no toolchain and run on any distro. Also cargo install epubveri, or @veripublica/epubveri-wasm on npm for the browser.

If you hit a disagreement with epubcheck, the most useful thing you can send is exactly what Doitsu sent: epubcheck's output and epubveri's, for the same book. It beats a description by a mile and costs you almost nothing.

[Kayadelenium]

epubveri 0.9.20 is out

https://github.com/veripublica/epubv...es/tag/v0.9.20

Same-day follow-up to 0.9.19, and a smaller post because the changes are smaller: nine fixes, eight of which came from diffing epubveri's output against epubcheck's over a local corpus of 346 real books, one book at a time.

Two of them were epubveri reporting too much, which is the half worth naming:

- A remote font in a shared stylesheet was reported once per document that linked the sheet — one @font-face produced 19 findings on a ten-document book where epubcheck produces*2.
- A reference to a resource that is declared in the manifest but missing from the container drew a second error on top of the right one.

The rest close gaps in the other direction: a reference to a container file that no manifest item declares (including inside SVG, which was silent entirely), remote resources in EPUB 2, unencoded spaces and empty hosts in URLs, and dc: metadata that Calibre fills with unescaped markup.

Where it stands against epubcheck 5.3.0 on those 346 books: 343 agree on the reported message IDs exactly, and there is no ID that epubveri reports and epubcheck does not. The remaining differences are all in the other direction — things epubcheck catches that epubveri still misses, plus two that are epubcheck's own artefacts.

- cargo install epubveri,
- 8 prebuilt binaries on the release page,
- or try it in the browser with no install: https://veripublica.github.io/epubveri/

[Kayadelenium]

epubveri 0.9.21 and 0.9.22 — a CSS false positive fixed, and SVG reference checking completed

Two releases since 0.9.20. The first fixes a false positive worth knowing about if you use @keyframes; the second is parity work on SVG references, including one case where we were the ones inventing an error.

0.9.21 — @keyframes no longer reports a CSS syntax error

A @keyframes block was read as a list of declarations, so 0% { opacity: 0 } came back as one malformed declaration: CSS-008, on perfectly valid CSS, on a construct that appears in every animated fixed-layout book. epubcheck reports nothing there. @-webkit-keyframes, @-moz-keyframes, @starting-style and any at-rule newer than our list failed the same way — four shapes, one cause.

The cause was that the table deciding "does this block hold rules or declarations?" lived in the validator rather than in the CSS parser. It has moved to the parser (styloria 0.11), which also means an at-rule neither tool has heard of is now read leniently instead of drawing an error.

Also in 0.9.21: a nested at-rule inside a style rule (.a { @media print { … } }, @nest) is now reported. We already reported the nested style rule form; the at-rule form was silent for no good reason.

0.9.22 — RSC-014 across every reference kind, and one false positive of ours removed

RSC-014 is a type-matching check: epubcheck gives every id a type from the element carrying it (SVG symbol, gradients/pattern, clipPath, or generic) and requires each reference to match. We had implemented exactly one cell of that. Now covered: hyperlinks (cross-document too), SVG <a xlink:href>, <use>, fill/stroke="url(#…)", cite on blockquote/q/ins/del, and a media overlay's <text src>. A fragment that resolves to nothing is RSC-012, which closed three silent gaps along the way.

The part worth flagging: an SVG <a> is now read through xlink:href only. Our anchor walk matched on element name and always read the plain href, so for SVG anchors every check in it was inverted against epubcheck — a plain href="#sym" drew RSC-014 from us and nothing from epubcheck. That is gone.

Two epubcheck bugs found while doing this, both filed upstream

- w3c/epubcheck#1677 (https://github.com/w3c/epubcheck/issues/1677) — SVG references are read from xlink:href only, so SVG 2's plain href is never checked. <image href="missing.png"> — a missing file — draws nothing, while the xlink spelling is RSC-007.
- w3c/epubcheck#1678 (https://github.com/w3c/epubcheck/issues/1678) — clip-path="url(#…)" is never checked; no reference is registered with that type, so the branch handling it is unreachable.

Until those are resolved I deliberately mirror the silence rather than report where epubcheck doesn't — reporting extra errors is worse than missing them, for a tool people run alongside epubcheck.

Honest limits: none of the 356 real books I test against defines an SVG symbol, gradient, pattern or clipPath, so this family is verified by enumeration against epubcheck (twenty shapes, one book per run) and unit tests rather than by real-world coverage. One known gap is left on purpose: an SVG <a xlink:href="missing.xhtml"> does not yet draw RSC-007.

Downloads: 8 pre-built binaries on the releases page (https://github.com/veripublica/epubveri/releases) (Linux gnu/musl, macOS, Windows — x86_64 and aarch64), the crate on crates.io, and the WASM build on npm.

[Doitsu]

@Kayadelenium:

epubveri does not flag incomplete nav/ncx files.

NAV:

<body epub:type="frontmatter">
  <nav epub:type="toc" id="toc" role="doc-toc">
    <h1>Table of Contents</h1>
  </nav>
  <nav epub:type="landmarks" id="landmarks" hidden="">
    <h1>Landmarks</h1>
  </nav>
</body>

NCX:

<navMap>
  <navPoint id="navPoint1">
    <content src="Text/Section0001.xhtml" />
  </navPoint>
</navMap>

EPUBCheck reported 3 errors and a warning.

[JSWolf]

Originally Posted by Kayadelenium

Two epubcheck bugs found while doing this, both filed upstream

- w3c/epubcheck#1677 (https://github.com/w3c/epubcheck/issues/1677) — SVG references are read from xlink:href only, so SVG 2's plain href is never checked. <image href="missing.png"> — a missing file — draws nothing, while the xlink spelling is RSC-007.
- w3c/epubcheck#1678 (https://github.com/w3c/epubcheck/issues/1678) — clip-path="url(#…)" is never checked; no reference is registered with that type, so the branch handling it is unreachable.

Until those are resolved I deliberately mirror the silence rather than report where epubcheck doesn't — reporting extra errors is worse than missing them, for a tool people run alongside epubcheck.

if there's a bug in epubcheck and you know of it, I'd prefer epubveri fixes it.

[Kayadelenium]

epubveri 0.9.23 — two reference checks, and a case where I decided not to match epubcheck

A small follow-up to the 0.9.21/0.9.22 post.

Two checks that were narrower than they looked

RSC-010 ("reference to non-standard resource type") was only wired to the two table-of-contents paths here — an NCX <content src> and a nav toc link. epubcheck applies it to every hyperlink, so an ordinary <a href="styles.css"> drew nothing from me. It does now, XHTML and SVG anchors alike.

RSC-007 for an SVG <a xlink:href="missing.xhtml"> was also missing: the existence check reads no-namespace attributes and an SVG anchor addresses its target with the namespaced spelling. All eight anchor shapes I test now agree with epubcheck 5.3.0.

The part worth reading: a finding I chose not to match

While testing the above I hit a case where the two tools disagree about which message to report, and digging into it turned up something in epubcheck.

Take a media overlay whose <text src> points at a resource that isn't a content document. epubcheck reports RSC-010. I report MED-013 — "this content document declares a media overlay, and that overlay never references it back". Both tools report exactly one message and both call the book invalid.

The control settled what was going on: point the overlay at a valid content document instead, and both tools report MED-013 and MED-010, agreeing exactly. So epubcheck's MED-013 works fine — it goes quiet in the first case because its RSC-010 throws CheckAbortException, which stops the remaining checks for that reference and takes an unrelated package-level finding down with it.

Those are two independent defects. Silencing the second costs a round trip: fix the <text src>, re-run, and only then learn the overlay never pointed at your document.

I'm keeping MED-013 rather than matching, and it's documented as a deliberate divergence — the verdict is INVALID either way, so nothing about the outcome differs, and copying the behaviour would mean reproducing a suppression rather than implementing a check.

Filed upstream as w3c/epubcheck#1679 (https://github.com/w3c/epubcheck/issues/1679), with the three-book reproduction. Their own #221 (https://github.com/w3c/epubcheck/issues/221) — "css syntax error masks missing resources" — was accepted and fixed for the same reason back in 2012, so there's precedent for treating this class as a defect.

That brings my open upstream reports to three: #1677 (https://github.com/w3c/epubcheck/issues/1677) (SVG 2's plain href never checked, including a missing <image> target), #1678 (https://github.com/w3c/epubcheck/issues/1678) (clip-path references unchecked), and this one.

Downloads as usual: 8 pre-built binaries on the releases page (https://github.com/veripublica/epubveri/releases), the crate on crates.io, the WASM build on npm.

[Kayadelenium]

Both of those are fixed in 0.9.24, out now.

You were right on both counts, and neither was a near miss — the NCX and the navigation document simply had no content-model check. A navPoint with a <content> and no <navLabel> was accepted, and a <nav> with no <ol> returned silently from the function that was supposed to require it. Your book now produces the same four findings epubcheck does, on the same elements.

The test file made this quick, and that's worth saying plainly: one 2.4 KB book isolating three separate shapes, next to epubcheck's own output, is far more useful than a description of the problem. It took the guesswork out entirely.

Checking your report properly also turned up two more nav rules that were implemented at one end only — a second toc nav wasn't reported, and empty headings were only checked inside a <nav> rather than anywhere in the document. Both fixed in the same release.

One caveat on my side: no book in our 356-book test corpus has a landmarks nav with anything other than exactly one ol, and the corpus carries only 8 headings across its 66 navigation documents. So these rules are held by fixtures measured against epubcheck rather than by real-world coverage. If you hit anything that looks wrong, that's the thinnest part.

Thanks — this was the most efficient report we've had.

[JSWolf]

Please fix bugs in epubcheck in epubveri. Don't wait to see if epubcheck gets fixed.

[Kayadelenium]

Originally Posted by JSWolf

Please fix bugs in epubcheck in epubveri. Don't wait to see if epubcheck gets fixed.

Point taken, and it's already partly how I work — where epubcheck loses a finding to its own error handling, I report it rather than reproduce the gap.

Where I'm still working out the line is the other kind: things epubcheck simply doesn't check. Some of those are plainly broken books, like an SVG image whose file isn't in the EPUB — hard to argue anyone wants that to pass. Others are closer to judgement calls, and reporting an error the reference tool doesn't give can cost a user real time when the ingestion gate they're up against is still epubcheck.

So the answer is probably not one policy but two: fix the clear defects outright, and put the judgement calls behind the --advisory flag, which already exists for exactly this and never changes the valid/invalid verdict.

We do file these upstream as we find them — not to wait for a fix, but so there's a record of what we diverged on and why.

Thanks for pushing on it. This is the kind of thing that's much easier to get right with people arguing about it out loud.

[JSWolf]

Originally Posted by Kayadelenium

Point taken, and it's already partly how I work — where epubcheck loses a finding to its own error handling, I report it rather than reproduce the gap.

Where I'm still working out the line is the other kind: things epubcheck simply doesn't check. Some of those are plainly broken books, like an SVG image whose file isn't in the EPUB — hard to argue anyone wants that to pass. Others are closer to judgement calls, and reporting an error the reference tool doesn't give can cost a user real time when the ingestion gate they're up against is still epubcheck.

So the answer is probably not one policy but two: fix the clear defects outright, and put the judgement calls behind the --advisory flag, which already exists for exactly this and never changes the valid/invalid verdict.

We do file these upstream as we find them — not to wait for a fix, but so there's a record of what we diverged on and why.

Thanks for pushing on it. This is the kind of thing that's much easier to get right with people arguing about it out loud.

It makes no sense to me to ignore errors that epubcheck miss or incorrectly reports. It's good that you'll do this. Thank you.

[Doitsu]

Originally Posted by Kayadelenium

Both of those are fixed in 0.9.24, out now.

For completeness's sake epubveri should also flag the following in NCX files.

Empty pagelist:

<navMap>
     <pageList>
     </pageList>
</navMap>

ERROR(RSC-005): Error while parsing file: element "pageList" incomplete; missing required element "pageTarget"

Empty navMap:

<navMap>
</navMap>

ERROR(RSC-005): Error while parsing file: element "navMap" incomplete; missing required element "navPoint"

Both are flagged by EPUBCheck.

[Kayadelenium]

epubveri 0.9.25

@Doitsu — your empty <pageList> and empty <navMap> are both reported now, and thank you for it, because the report turned out to be the visible corner of something larger. The NCX had exactly one structural check in it (the navPoint model added yesterday, also from your report). Everything else the format requires was unchecked.

So rather than adding two checks, 0.9.25 validates the NCX against a grammar. Sixteen shapes were measured one book at a time against epubcheck 5.3.0, and all sixteen agree with it on both the message ID and the number of findings: the empty containers (navMap, pageList, navList, navLabel), a navTarget or pageTarget with no <content>, a missing <navMap> or <head><meta>, a <pageList> nested inside the navMap or placed before it, an element or attribute the format does not define, a navPoint with no id, a <content> with no src, and markup inside <text>.

The count mattered more than I expected. The first build reported three findings where epubcheck reports one, because the grammar and the hand-written navPoint check were both seeing the same defect. A test that only asserted "something was reported" would have passed.

One change that affects every book, not just ones with an NCX. epubveri used to say

element "html" has incomplete content

where epubcheck says

element "html" incomplete; missing required element "body"

That was the same shortfall on every XHTML document, and it took writing the NCX grammar to notice it. Both of epubcheck's message forms are now produced — the element the model demands next, or the list of alternatives when the model offers a choice. Across my 356-book test corpus, 6,244 of 6,247 such findings now name something; before, 32 did. The remaining three are an empty <guide>, whose model admits any element, so there is no name to give.

Also in this release: a content document that fails to parse no longer loses the checks below the failure. A book with a missing stylesheet and a stray & used to report only the entity, so you fixed that, re-ran, and only then met the other problem. epubcheck's parser keeps what it passed before the failure; this now recovers the same set, and stops at the same place it does.

Downloads: 8 pre-built binaries on the releases page (https://github.com/veripublica/epubveri/releases) (Linux gnu/musl, macOS, Windows — x86_64 and aarch64), the crate on crates.io, and the WASM build on npm.

[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>