Possible replacement for EPUBCHECK

[Kayadelenium]

@Doitsu — thanks very much for the three reports. All three are fixed, and I dug into the root of each rather than just patching the symptom:

1. epub:type="biblioref" (OPF-088). You were right — and it turned out not to be one term but a whole class. epubveri's default epub:type vocabulary was missing 29 current terms from epubcheck's aggregate (the Dictionary, Comics and Structure vocabularies — biblioref, dictionary, dictentry, part-of-speech, balloon, panel, …), plus a spelling bug (concludingsentence where the real term is concluding-sentence). The vocabulary now mirrors epubcheck's, so the whole class is gone.

2. width="50%" on <img> (RSC-005). This was an EPUB 2 vs EPUB 3 difference. In XHTML 1.1 (EPUB 2), width/height are the Length datatype — pixels or a percentage — which epubcheck accepts; epubveri was applying the stricter HTML5 rule (integer only) to EPUB 2 as well. Now EPUB 2 accepts the percentage and EPUB 3 still rejects it, matching epubcheck on both versions.

3. OPF-096 message. Agreed the old wording wasn't helpful. It now points at thr="no"> and spells out the cause (no inbound hyperlink), instead of the package root.

These shipped in 0.7.3. The current release is 0.7.4, which also adds a few checks that came out of a full audit against epubcheck's message set — CSS-006 (position: fixed), NAV-001 (an EPUB 3 nav document in an EPUB 2 book), NCX-004 (whitespace in dtb:uid), a

That audit is now published as a per-message-ID coverage matrix, in case it's : https://github.com/veripublica/epubv...cs/COVERAGE.md — it'shonest about the gaps, too.

Thanks again. The community's testing is driving nearly every fix, and different people keep finding different things — please keep throwing real books at it.

[Kayadelenium]

Quick follow-up — epubveri 0.7.5 is out, continuing the same audit against epubcheck's message set.

New since 0.7.4:

- OPF-044 — a spine item whose fallback chain exists but never reaches a content document is now reported separately from OPF-043 (no fallback at all), matching epubcheck's two distinct IDs.
- NAV-004–NAV-008 — the EDUPUB nav-completeness checks: an incomplete heading hierarchy in the toc (NAV-004), or content documents containing <audio>/<figure>/<table>/<video> with no matching loa/loi/lot/lov list in the nav (NAV-005–008).
- Image error mapping now matches epubcheck exactly — MED-004 is reserved for a file too short to contain an image header; a longer file whose header matches no known format is a declared/actual mismatch (OPF-029), not MED-004.

All additive — no verdict changes on the epubcheck test corpus. The coverage matrix is updated too: epubveri now matches about 90% of epubcheck's live (non-suppressed) checks.
→ https://github.com/veripublica/epubv...cs/COVERAGE.md
→ https://github.com/veripublica/epubveri/releases (binaries + full changelog)

Thanks again — keep the reports coming; real books keep surfacing what the synthetic corpus misses.

[Doitsu]

@Kayadelenium

The following table is flagged by epubveri in an epub2 book:

ERROR RSC-005: attribute "colspan/rowspan/span/width" is not allowed here
EPUBCheck reports no errors.

<table border="1">
  <colgroup>
    <col span="2" width="100" style="background-color: #f0f0f0;"/>
    <col width="80" style="background-color: #d0e8ff;"/>
  </colgroup>

  <thead>
    <tr>
      <th colspan="3">Quarterly Report</th>
    </tr>
    <tr>
      <th>Month</th>
      <th>Product</th>
      <th>Sales</th>
    </tr>
  </thead>

  <tfoot>
    <tr>
      <td colspan="2">Total</td>
      <td>215</td>
    </tr>
  </tfoot>

  <tbody>
    <tr>
      <td rowspan="2">January</td>
      <td>Widgets</td>
      <td>120</td>
    </tr>
    <tr>
      <td>Gadgets</td>
      <td>95</td>
    </tr>
    <tr>
      <td>February</td>
      <td colspan="2">Data pending</td>
    </tr>
  </tbody>
</table>

In an EPUB3 book, epubveri only reported ERROR RSC-005: attribute "width" is not allowed here
EPUBCheck complained about width and tbody.

[Kayadelenium]

@Doitsu — fixed in 0.7.6, thanks for the report.

The EPUB 2 side was a genuine bug. My schema had the table subtree carrying only the global attributes, so the whole XHTML 1.1 Tables Module set was missing — colspan/rowspan on cells, span/width on col, the alignment attributes on rows and row groups. Your table now validates clean. border was wrong for the same reason: I had it restricted to HTML5's ""/"1", but XHTML 1.1 allows any number, so border="2" was being rejected too.

Same class of bug as the width="50%" one you found earlier, incidentally — both times the EPUB 2 branch of the schema was built lean and I never filled the module's attributes back in.

On the EPUB 3 half of your report: the width error is correct — it's obsolete on <col> in HTML5, and EPUBCheck flags it too. EPUBCheck is also right about tbody: HTML5 wants tfoot after tbody. I don't catch that one, and that's deliberate for now — my schema is permissive about element ordering, which keeps false positives down but means I miss real nesting violations like this one. Worth revisiting, but it's a bigger change than a missing attribute.

0.7.6 is up on the releases page (binaries for 8 platforms), crates.io, and npm.

[Kayadelenium]

epubveri 0.7.10 — mostly a false-positive clear-out for EPUB 2 books.

Since 0.7.6 the main work has been on EPUB 2, and it was not flattering. Ten separate cases turned up where epubveri rejected markup that EPUBCheck accepts. All had the same cause: a rule that only applies to EPUB 3 was being applied to EPUB 2, where XHTML 1.1 is the more permissive spec.

The one most likely to have bitten you:

<a name="anchor"> was drawing RSC-005. That is the classic pre-id anchor form, so internal links in a lot of older EPUB 2 books were being reported as errors. Also fixed: an empty <title>, lang and xml:lang differing on the same element, a nested <dfn>, the legacy <tours> element, and several missing attributes on <a> and <img> (target, charset, rel, rev, longdesc, usemap, and more).

@Doitsu found three of these — the img width/height case, the table attributes, and by extension the whole class. After the third one it was clear that waiting for reports was the
wrong approach, so I went through EPUBCheck's own EPUB 2 schemas rule by rule what epubveri does. That turned up the remaining seven before anyone hit them.

Worth mentioning for anyone who cares about testing: my test corpus could not UBCheck's own test files are synthetic and sparse for EPUB 2 — the corpusresults were byte-identical before and after all ten fixes. Real books are the only thing that finds this class, which is exactly why forum reports have been more valuable here than
any automated suite.

New checks in the same period:

- Malformed CSS selectors are now reported (a > > b, [href=], and so on). Delithing newer than the checker is accepted rather than flagged, so modernselectors like :has() or :art() won't produce spurious errors.
- Six NCX checks completing EPUBCheck's set: playOrder must start at 1 and havg at the same target must share a playOrder, pageTarget value/type combinations must be unique, and repeated xml:lang on sibling navLabel elements.
- Empty href="", a metadata <link> that is also a manifest item, an unusual cod two prefix declaration errors.
- A stylesheet starting with a UTF-8 BOM is no longer mis-parsed.

Downloads (8 platforms, no install, no Java): https://github.com/veripublica/epubv...es/tag/v0.7.10

Also on crates.io and npm if you want to embed it.

If you run it over a book and get an error you don't believe, please post it. Three of this month's ten fixes started that way, and false positives are the thing I most want to hear about — a validator that cries wolf is worse than one that misses something.

[Doitsu]

False positive:

OPF:
<item id="Section0001.xhtml" href="Text/Section0001.xhtml" media-type="application/xhtml+xml" properties="svg"/>

HTML:
<p>Lorem ipsum dolor.<img alt="checkmark" src="../Images/checkmark.svg"/></p>

ERROR OPF-015: the "svg" property is declared but doesn't appear to be needed.

In this case the svg property is optional but not an error.

Not reported:

<p>Tom & Jerry</p>
<ol></ol>
<ul></ul>
<table></table>
<dl></dl>

FATAL(RSC-016): Fatal Error while parsing file: The entity name must immediately follow the '&' in the entity reference.
ERROR(RSC-005): Error while parsing file: element "ol" incomplete; missing required element "li"
ERROR(RSC-005): Error while parsing file: element "ul" incomplete; missing required element "li"
ERROR(RSC-005): Error while parsing file: element "table" incomplete; expected element "caption", "col", "colgroup", "tbody", "tfoot", "thead" or "tr"
ERROR(RSC-005): Error while parsing file: element "dl" incomplete; expected element "dd" or "dt"

IMHO, "The entity name must immediately follow the '&' in the entity reference." might not be understood by beginners. May something like "'&' must be replaced with '&amp;'" would be better.

[Kayadelenium]

@Doitsu — all three fixed in 0.7.12, thanks. The first one was worse than it looked.

The bare &. You reported it as "not reported", but it was doing more damage than that: the whole content document was being skipped. I put <p>Tom & Jerry</p> and an obsolete <center> in the same file and epubveri reported neither — the book came back valid. The parse failed, and the failure was being swallowed.

The cause was two checks each assuming the other owned it. Malformed-entity errors from the parser are suppressed on the grounds that a separate raw-text scan reports them with better positions — but that scan only looked at & followed by a name, and walked straight past a & followed by a space. So nothing reported it, and because the document never parsed, every other check on it was dropped too.

That is the worst shape a validator bug can take. A missing rule you eventually notice; silence you don't. Fixed, and I took your wording suggestion — it now says:

FATAL(RSC-016): a bare '&' must be written as '&amp;'

rather than repeating the parser's complaint about entity names.

Empty <ol>/<ul>/<dl>/<table>. Now reported — but only for EPUB 2, and that turned out to be the interesting part. XHTML 1.1 requires content in all four (ol is oneOrMore li, and the table model ends in tbody+ | tr+). HTML5 relaxed every one of them to zero-or-more, so an empty <ul> in an EPUB 3 book is genuinely valid and EPUBCheck accepts it there. If I had made the rule version-wide I would have traded a missed error for a false positive, which is the worse trade.

One limitation, since you'll hit it: with all four empty in the same file I curst, where EPUBCheck reports all four. The book is still invalid, but you'll be fixing them one run at a time. That's a separate change in the schema engine's error recovery and it's on the list.

The svg property. You were right, and EPUBCheck's own source says so — there is a comment in OPSHandler30 reading "the svg property MAY be set if an SVG resource is referenced in
HTML". It tracks two separate sets: properties that are required (the documentsing declaration is OPF-014) and properties that are merely allowed (thedocument references an SVG resource — declaring it is optional). I had only the first, so your <img src="checkmark.svg"/> case got rejected. Both are tracked now.

Worth adding: my first attempt at that fix collapsed the two into one flag, which quietly created the opposite false positive — demanding properties="svg" from any document that links to an SVG image. The test now pins all three directions.

0.7.12 is on the releases page, crates.io and npm. Keep them coming — three red one of them was a silent one I would not have found on my own.

[Kayadelenium]

epubveri 0.8.0 released (with 0.7.14)

Fixed

- A malformed numeric character reference — "", "", "&#zz;", an unterminated "&#38" — no longer silences a whole content document. The file failed to parse and was then dropped from every check without a word, so a book with real errors in it could report VALID. The suppression that caused it now requires a finding to have actually been produced, rather than assuming another check covers the case. (Same shape as the bare "&" in 0.7.12 and "&nbsp;" under an XHTML 1.0 doctype in 0.7.13.)

- An NCX, a Media Overlay, META-INF/metadata.xml or a rendition mapping document that is not well-formed XML is now reported as RSC-016. All four were skipped silently, and nothing else in the tool parses them — a "</navMapX>" typo produced output identical to a valid NCX.

- PKG-023 now keys on the version being validated against rather than the one the package document declares (relevant with -v, below).

Added

- -v / --epub-version <2|2.0|3|3.0>: validate against the version you name, whatever the book declares — epubcheck's -v. On a disagreement PKG-001 reports it and the requested version wins, as epubcheck does. Note that -V still prints epubveri's own version.

- PKG-018: an input file that does not exist is reported with its message ID, so JSON output carries it like any other finding. Exit code unchanged.

- PKG-023: --profile against an EPUB 2 book now reports that profiles do not apply, instead of ignoring the request silently.

Changed

- Coverage against epubcheck: 190 of 197 live checks (~96%), up from 187/198. Per-ID matrix in docs/COVERAGE.md.

- Library API (breaking; CLI and WebAssembly unaffected): Options gained a field, so a struct literal needs ..Options::default(); opf::check now takes &Options instead of separate profile and advisory parameters.

Download: https://github.com/veripublica/epubv...ses/tag/v0.8.0
Binaries for Linux, macOS and Windows on x86_64 and ARM; the Linux musl builds are static. No JVM required.

[JSWolf]

Does anyone actually have an ePub 2 but not ePuib 2.0 eBook?

[DNSB]

Originally Posted by JSWolf

Does anyone actually have an ePub 2 but not ePuib 2.0 eBook?

I've seen, going off memory, 6 books (4 from the same publisher) that claimed to be ePub2 but the entire book was ePub3 other than the 'version="2.0"' string in the OPF document. Sigil's FlightCheck was very unhappy with them.

[Doitsu]

@Kayadelenium

One more false positive in epub3 books.

<hgroup>
<h1>Frankenstein</h1>
<p>Or: The Modern Prometheus</p>
</hgroup>

ERROR RSC-005: element "p" is not allowed here

[Kayadelenium]

3Doitsu — you were right, and it is fixed in 0.8.1 (out now).

epubcheck's content model for hgroup is exactly one heading, interleaved with any number of <p> elements. Mine was "one or more headings, no paragraphs", which rejected the shape you posted — a title with its subtitle as a paragraph, which is the ordinary modern way to write it.

There is a second half to that fix, and I would rather you hear it from me than meet it in your own book. My old definition accepted this:

<hgroup><h1>Frankenstein</h1><h2>Or: The Modern Prometheus</h2></hgroup>

That was the canonical hgroup until HTML dropped it in 2022 — the subtitle is a <p> now, not a second heading. epubcheck's schema (hgroup.inner, in sectional.rnc) admits exactly one h1–h6, so it should flag the two-heading form; I read that in their source rather than running it, so if you find epubcheck accepts it in practice, please say so and I will look again.

So from 0.8.1, books written to the old model will start drawing RSC-005 here where they did not before. I decided to match epubcheck rather than stay quiet about it. A validator that hides a disagreement with the reference implementation is not much use, and nothing epubveri does can repair the markup either way — that belongs to whatever produced the book.

No corpus fixture covers hgroup in either direction, so their schema was the only evidence available. That is the same footing as the EPUB 2 false positives cleared out earlier this month, and it is why reports like yours matter more here than the test suite does: the suite was green through every one of those bugs.

JSWolf — "2" and "2.0" are just two spellings of the same thing in that flag, because epubcheck accepts both and I wanted a copied command line to behave identically. The OPF version attribute for EPUB 2 is "2.0"; I am not implying there is some other EPUB 2.x out there.

DNSB — your six books are the case the flag is actually for. If the OPF says version="2.0" but the contents are EPUB 3, `epubveri -v 3.0 -i book.epub` checks it against EPUB 3 regardless of what the package document claims, and reports PKG-001 to say the two disagree. The same works the other way with -v 2.0. It will not tell you which of the two the book was meant to be, but it will tell you which one it actually satisfies.

[JSWolf]

Can you have epubveri auto-detect which ePub version it is based on the code and then report the version string might be incorrect?

[DNSB]

Since those books were a few years back, I took an existing ePub3 of snippets published in the Ilona Andrew's newsletters for This Kingdom Will Not Kill Me that I generated for my own use.

The original version with the version=3.0 shows no errors with epucheck 5.3.0 and epubveri 0.8.1.

After changing the version to 2.0, both epubcheck and epubveri were not happy campers though epubveri came up with 8 errors while epubcheck came up with 19 (see the attached text files).

[Doitsu]

@Kayadelenium

epubveri doesn't like this complex CSS3 media query and reports

ERROR CSS-008: CSS syntax error

@media all and (prefers-color-scheme: dark){
	img[epub|type~="se:image.color-depth.black-on-transparent"]{
		filter: invert(100%);
	}

	img[epub|type~="se:image.color-depth.black-on-transparent"][epub|type~="se:image.style.realistic"]{
		background: currentColor;
		filter: none;
	}
}