epubveri – standalone EPUB validator

[DNSB]

Originally Posted by JSWolf

When checking the eBooks in calibre (not the editor), it would be good to know if any of the eBooks have HTML files that are too large. calibre's check book does not work outside the editor. The thing is, do you really want to make us have to run Quality Check before or after running epubvari? That's adding more work to check eBooks. It's best to have everything in one app to run once.

Jon, I was under the impression that epubveri was intended as a replacement for epubcheck without the need for the rather hefty Java overhead and was never intended to be a one step check everything in an ePub tool. Scope creep is a pestiferation.

I do not mind using multiple tools to check my ePubs—perhaps my age is showing there since I like small tools that do one job and do it well. Quality Check is just one of the tools I use on my Intake library and I neither expect nor want epubveri to replace all of them.

[JSWolf]

I found an issue with both epubckeck and epubvari. This happens with both ePub2 and ePub3.

The content in the meta name="cover" is supposed to be the id of the cover image. But it it isn't and both epubckeck and epubvari don't report this error.

<meta name="cover" content="fig_backad"/>
<item href="images/cover.jpg" id="cover_image" media-type="image/jpeg"/>

[DNSB]

Not even the obsolete meta element for ePub3?

[Jellby]

I believe the ePub2 spec says nothing about covers. The meta name="cover" tag is just an arbitrary tag that can contain whatever, it's up to reading systems to decide what to do with it. The de facto (calibre) standard may be having the file id, but nothing in the spec mandates it.

[Kayadelenium]

@JSWolf, @Jellby, @DNSB: Jellby is right. Neither EPUB 2 nor EPUB 3 defines <meta name="cover">; it's a convention that calibre and Kindle use. epubcheck has no rule for it, which I checked in its source, so it isn't an error, and neither tool should report it as one. DNSB, in EPUB 3 epubveri reports the element itself as outdated (OBS-001, as a usage), but that says nothing about what it points to.

Still, a cover meta that names nothing is a real defect for the readers that rely on it. So it's a candidate for an advisory, which is off by default and never changes the verdict. On my shelf, 436 of 474 books carry this meta, and every one points at an existing image. So it would only fire on books that are actually broken, like the one you found. I'll look at it before promising anything, mainly to see whether some tools write a file path there instead of an id.

[JSWolf]

The file path is not part of the meta name="cover". content points to the ID of the cover.

If there is a file path, then it's an error.

Here is a link from The Daisy Consortium showing this is how you define a cover for ePub2.

https://kb.daisy.org/publishing/docs/epub/cover.html

[DNSB]

Originally Posted by JSWolf

The file path is not part of the meta name="cover". content points to the ID of the cover.

If there is a file path, then it's an error.

Here is a link from The Daisy Consortium showing this is how you define a cover for ePub2.

https://kb.daisy.org/publishing/docs/epub/cover.html

And that last part of that description which reads:

In this case, the content attribute references the ID of the manifest item for the image. (Note that this practice is not officially part of the EPUB 2 specification, but is recognized by EPUB 2 reading systems.)

[JSWolf]

But without <meta name="cover"... some programs won't know the cover. So it is rather important to have this be correct.

[Kayadelenium]

Thanks for the Daisy link, that's the useful part: it shows where the convention comes from.

I went to the specs to see what they say, EPUB 2 included, since that's where this convention lives.

• OPF 2.0.1 defines meta only as a free name/content pair ("arbitrary metadata beyond the data described by the Dublin Core specification"). Its schema puts no restriction on the name values and no link between content and a manifest id. The OPS and OCF documents don't mention it either. The only cover mechanism EPUB 2 actually defines is a guide reference with type="cover".
• EPUB 3.4 lists the OPF 2 meta element among its "outdated features" (E.1): reading systems ignore it, and the spec advises checkers not to alert on its presence. The EPUB 3 way to mark a cover is the cover-image property on the manifest item (D.6.1).

So you're right that a content value naming no manifest item is a broken reference by the convention calibre, Kindle and Adobe use, and DNSB and Jellby are right that no spec, EPUB 2 or 3, defines that convention, so it can't be an error or a warning. What that leaves is an optional note. I'd word it as "the cover meta names no manifest item", and I wouldn't claim what a given reader will do with it.

Before I decide anything, I'd like some real cases from you. Is it always an id that doesn't exist (like your fig_backad), or have you seen a file name or a path in content? And roughly how many books in your library does it hit? On my own shelf of 524 books, 490 carry the meta and all 490 name an existing manifest item, so a check would fire on none of them, which tells me nothing about libraries like yours. I'm not promising it yet, but a few real examples would settle it.

[DNSB]

I did a search on 17758 ePubs for '<meta name="cover"' in the .opf file. The search returned 17192 results.


The results were:

14,270 had '<meta name="cover" content="cover"/>'
741 had '<meta name="cover" content="cover" />'
539 had '<meta name="cover" content="cover-image"/>'
59 had '<meta name="cover" content="my-cover-image"/>'
52 had '<meta name="cover" content="cover_img" />'
48 had '<meta name="cover" content="my-cover-image" />'
43 had '<meta name="cover" content="cover_img"/>'
35 had ''<meta name="cover" content="x_cover-image" />'

For a total of 15,787 though some of those variants were from placing a space before the closing /.

The rest were a mix of filenames (cover.jpg was popular) and what looked like random IDs/ISBNs/book titles/etc. There was only 11 examples where the contents= did not match the ID in the file. As far as I could tell, those were from I had replaced a cover image and the ID was not updated.

I randomly checked the remaining block of ePubs where the '<meta name="cover"' search string was not found and they were a mix of old ePub2 files and ePub3 files.

The joys of sucking a text file into a spreadsheet and then sorting wildly.

[Kayadelenium]

epubveri 0.19.0 is out: GitHub release, crates.io and npm. The Sigil and calibre plugins pick it up on their own.

This release is about references: links, table-of-contents entries, media overlay text links and the like, and how each of them is counted. A user on Reddit ran epubcheck and epubveri side by side on 100 of their own books and shared the results. Of the 99 books epubcheck could finish, the two tools agreed on 98. The one disagreement was an extra error from epubveri, and tracing it led me through every place epubveri resolves a reference. I compared each one with epubcheck on a small test book of its own.

What this means for your books:

• Most books get exactly the same report as before. On my own shelf of 544 books, two reports changed, and both now match epubcheck.
• A link to a file that the manifest declares but the EPUB does not contain now gets only RSC-001, as in epubcheck. epubveri used to add an RSC-007 for the same missing file. If the link has a #fragment, it now also gets RSC-012, which epubcheck reports as well.
• RSC-010 and RSC-011 are now reported for every link, not once per target. A book with 35 links to images got 29 findings from epubveri and 35 from epubcheck; now both give 35. An image map's area element now counts as a link too.
• The reading order checks now work the way epubcheck's do. That covers MED-015 for media overlays and NAV-011 for the table of contents, including fragments such as epubcfi(...) and empty ones.
• If two manifest items share the same id, the first one no longer counts as declared, and its file now gets OPF-003, as in epubcheck.

That means a book may now get errors it did not get before. They are errors epubcheck already reports, which is why this is 0.19 and not 0.18.1.

Two wrong findings are gone. The RSC-007 described above, which the Reddit comparison found. And a media overlay that reached a chapter only through epub:textref made epubveri report MED-013 on that chapter, which epubcheck does not do.

It is also faster. Following the profile raeq posted on GitHub (#137), I profiled the two slowest books on my shelf. Validation of those 544 books now takes 9% less CPU time than without these changes. The speed changes did not change a single report, on any of those books or on W3C's 209 conformance publications. How much you gain depends on your books.

One more thing came out of that check. A few findings about remote resources and standalone SVG files were printed in a different order on each run, so two runs of the same book could look different when nothing had changed. They are now always in the same order.

epubveri and epubcheck still give the same message IDs on all 687 expected messages in epubcheck's own test suite.

DNSB, thank you for the cover numbers (#370). That answers the question I put to JSWolf in #369 better than my own shelf could: in 17,192 books carrying the cover meta, 11 had a content value naming no manifest item, and those came from covers replaced without updating the id. So a note for that case would be true every time it fired and would fire rarely, which is what an optional note needs. I haven't decided on it yet.

[Kayadelenium]

epubveri 0.21.0 — CSS errors that say what is wrong, two CSS false positives gone, and the two releases I did not announce here (0.19.1, 0.20.0).

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

If you use one of the plugins, there is nothing to do: all three fetch the latest release on their own.

What can change on your books. Two CSS shapes that epubcheck passes were errors here, and now pass: an unquoted url() with a quote or a parenthesis in it that names a file the book really has, such as url(q'q.png), and a declaration written directly inside @media, as in @media print { color: red }. Two shapes epubcheck reports were missed here, and are now CSS-008 as there: a rule inside @font-face, and a value holding a { } block, as in p { color: red {} }. That second pair is why this is a minor release: a book with either can now fail where it passed. A book epubcheck passes still passes here.

CSS-008 now says what is wrong, and quotes it. It used to read "CSS syntax error" whatever the problem was, while epubcheck names the token it stopped at. A reader comparing the two tools on Reddit pointed that out, and they were right. It now reads like this, with the line and column as before:

• CSS syntax error: invalid selector '. h-10, . y-10' at '.'
• CSS syntax error: '{' is never closed
• CSS syntax error: 'margin-right' is not followed by ':'
• CSS syntax error: string '"abc' is broken by an unescaped line break
• CSS syntax error: rule 'a' inside a style rule

The last one is CSS nesting. EPUB defers to the CSS Snapshot, and nesting is not yet in the part of it that defines CSS, so it stays an error, as in epubcheck.

A broken url() is now read the way epubcheck reads it. CSS says an unquoted url() cannot contain a space, a quote or a parenthesis, and a browser never loads one that does. epubcheck takes everything up to the first ) as the address instead, and the verdict follows epubcheck, so url(a b.png) is now RSC-020 as there. What CSS says about it is the new ADV-015, shown only with --advisory and never part of the verdict.

From 0.19.1: ADV-014, with --advisory. A <meta name="cover"> whose content is not the id of any manifest item. This is the check JSWolf asked for in #362, and DNSB's count in #370 (11 such books among 17,192 that carry the meta) is why I was comfortable adding it: it is rare, and true every time it fires.

From 0.20.0: PKG-021 for an image whose header stops before its width and height, which epubveri used to pass in silence. Reported with a sample on GitHub (issue 138). It reads the same header epubcheck reads and nothing more, so it is never stricter than epubcheck.

Speed and repeatability. A file with very many findings no longer slows down out of proportion: 100,000 broken selectors in one stylesheet took 23 seconds and now take under one. And the same book now gives the same report on every run. Findings at the same spot could come out in a different order from one run to the next, which made two reports hard to compare. That is fixed, and every release is now checked for it before it goes out.

A correction to #371. The "15% less CPU" there was measured against a build that already contained 0.19.0's changes. Against 0.18.0 the figure was 9%, and 0.19.0 made a few books with many links in one large file slower, the worst from 0.11 s to 0.37 s. 0.19.1 fixed that. Since then every release is timed book by book against the previous release before it ships, and 0.21.0 passed that check on all 544 books on my shelf.

If a CSS-008 reads wrong on one of your books, the quoted text should make it quick to show me where.

[Kayadelenium]

How epubveri reads CSS now, and the CSS specification that changed on 1 October.

The CSS changes in 0.21.0 come from somewhere specific, so a few words on it. On 1 October 2026 the W3C published a new draft of CSS Syntax Level 3, the specification that says how a stylesheet is parsed. Its main change is how a block is read: a style rule's { } now holds declarations and nested rules side by side, which is how browsers already read CSS nesting.

CSS Syntax Module Level 3, Candidate Recommendation Draft of 1 October 2026

epubveri does not parse CSS itself. It uses styloria, a separate pure-Rust CSS parser I also write, published as its own library. styloria 0.12.0 follows that draft, and it came out the day after it. epubveri 0.21.0 is built on it.

https://github.com/veripublica/styloria

What that gives epubveri: the whole stylesheet comes back as one tree, with every block read by the same rules. Before, each at-rule's block had to be looked up in a table of which at-rules hold rules and which hold declarations. That table is where @media print { color: red } went wrong, and it is gone. The new reading also catches the two shapes I mentioned in #372 that were missed before, a rule inside @font-face and p { color: red {} }.

Why nested CSS is still an error. The parser now understands nesting, but EPUB decides whether it is allowed. EPUB 3.3 supports CSS "as defined by the CSS Working Group Snapshot". The 2026 Snapshot lists CSS Syntax in its official definition of CSS, and lists CSS Nesting in a separate section, among modules that are widely deployed but not yet part of that definition. So epubveri reports a nested rule as CSS-008, as epubcheck does. If a future Snapshot moves nesting into the definition, that answer changes with it.

One place I follow the specification rather than epubcheck. A string broken by a line break, as in content: "abc with the closing quote on the next line, ends at the line break in CSS. The quote that was meant to close it then opens a new string, and that one swallows the rest of its line, closing brace included. epubveri reports what that reading gives: the broken string, the second one, and the block that is now never closed. epubcheck skips ahead to the next ; { or } instead and reports one finding. Both call the book invalid, so the verdict is the same, but if you compare the two tools line by line, that is why the count differs there.

[Kayadelenium]

epubveri 0.24.0 - SVG is now checked the way epubcheck checks it, plus the three releases I did not announce here (0.21.1, 0.22.0, 0.23.0).

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

If you use one of the plugins, there is nothing to do: all three fetch the latest release on their own.

What can change on your books. In an EPUB 2 book, epubcheck checks SVG against the full SVG 1.1 grammar, and epubveri checked only part of it. Three kinds of mistakes it reports were missed here and are now errors, as there: an attribute on an element that does not take it (font-size on a rect, fill on a gradient stop), a keyword value the grammar does not allow (visibility="hide", or a version other than 1.1), and an SVG font without its font-face or missing-glyph. That is why this is a minor release: an EPUB 2 book with one of these can now fail where it passed. A book epubcheck passes still passes here, and none of the 544 books on my shelf changed.

EPUB 3 gets the same checks, as notes only. epubcheck runs its full SVG check on EPUB 3 as information, never as an error, and so does epubveri now. These show up only when usage messages are switched on, and they never touch the verdict. EPUB 3's grammar is not EPUB 2's: most keywords there must be written exactly, so visibility=" hidden " with spaces is reported in an EPUB 3 book and accepted in an EPUB 2 one, and visibility="collapse" is fine in EPUB 3 only.

Two false reports are gone. A keyword with spaces around it, such as fill-rule=" evenodd ", was an error here in both versions; epubcheck accepts it. And paint-order, transform-box and transform-origin were reported as unknown SVG attributes in EPUB 3, where they are allowed.

How I know these match. Every pair of SVG element and attribute, and every keyword value, went through epubcheck 5.4.0 and through epubveri, tens of thousands of cases at each version, and the findings came out identical, apart from two things left out on purpose: in EPUB 3, epubveri still accepts any aria- attribute name where epubcheck knows a fixed list, and it does not yet judge an SVG href the way epubcheck does. Both are misses, never false reports.

From 0.23.0. killo3967 reported three gaps on GitHub (issues 139, 140 and 141) and checked the fixes on their own books afterwards. A content document that is not well-formed now keeps the errors epubcheck finds before the break, a malformed SVG file is now an error instead of being skipped in silence, and stray text in the package metadata is now reported. The same release removed several false errors caused by a space at the edge of a value: at either end of prefix or of a manifest href, after an EPUB 2 media-type, and at the end of a link's fragment. An image or stylesheet used before a document's fatal error is also no longer reported as unused.

From 0.22.0. XML names and spaces are read the way epubcheck reads them. An EPUB 2 id with a combining accent (a letter stored as its base letter plus the accent) or a middle dot no longer fails. Neither does an EPUB 3 id holding a no-break space. In the other direction, a no-break space between list items is text, and is now reported as epubcheck reports it.

From 0.21.1. Only a new function for programs that read EPUB 2 files themselves. Nothing changes for books.

If an SVG finding reads wrong on one of your books, the element and attribute it names should make it quick to show me where.

[Kayadelenium]

epubveri 0.25.0 - in an EPUB 2 book, the style, script, meta and base elements in a document's head are now checked the way epubcheck checks them.

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

If you use one of the plugins, there is nothing to do: all three fetch the latest release on their own.

What can change on your books. In EPUB 2 (XHTML 1.1) each of these four elements takes only a short list of attributes. A style or script element must also say its type, and a base element must have an href. epubveri allowed all four the attributes most elements take, and did not require type or href. epubcheck reports these as errors, and now epubveri does too. Some examples: a class or id on a style element, a style element without type="text/css", a script element without a type, an id or lang on a script element, and a base element without an href. That is why this is a minor release: an EPUB 2 book with one of these can now fail where it passed. A book that epubcheck passes still passes here. None of the 544 books on my shelf changed, and 262 of its EPUB 2 books have a style element in the head. EPUB 3 books are not affected.

How it came up. I found it while testing kepubverto, my EPUB to KEPUB converter: epubcheck reported an error in an EPUB 2 book it produced, and epubveri called the same book valid. The gap turned out to be wider than that one attribute.

How I know these match. I built one small EPUB 2 book per case and ran each through epubcheck 5.4.0 and epubveri. That was 55 books, covering the attributes these four elements allow and the common ones they do not, plus title, head and link, which were already right. Before the fix, 29 of the 55 disagreed. Now none do, and in none of them does epubveri report something epubcheck does not.

One message ID changed. In an EPUB 2 book, a link element in the package metadata that points at a missing file is now reported as RSC-007w, the ID epubveri already used for EPUB 3, instead of RSC-007. It is still a warning. Only the ID changed, so that RSC-007 now means the same here as in epubcheck, where it is an error.

If one of the new errors shows up on a book where you did not expect it, the element and attribute it names should make it quick to show me.