Rules

wacz-validator runs a fixed set of rules over an archive and reports one issue per violation. The table is generated from the rule definitions themselves, so it cannot fall behind the code: name, severity, conformance level, per-profile overrides and spec links all come out of packages/core/src/validate/.

Reading the table

Conformance is what the spec demands — MUST, SHOULD, MAY, MUST NOT. Severity is what wacz-validator does about a violation.

Severity takes one of three values. Only error decides the verdict — an archive is usable exactly when summary.failed (the error count) is zero, and no number of warnings or infos overturns that.

Severity	Meaning	summary.failed
error	the archive cannot be used — replay breaks, or the check cannot be made	incremented
warning	worth fixing, but not broken on its own	unaffected
info	an observation, carrying no judgement	unaffected

Severity is decided by one thing only: whether the archive is usable. So datapackage/resources-complete is a MUST reported as a warning — an incomplete resources[] does not by itself break replay.

When you want the conformance view, read the conformance column. Handling the two axes separately is covered in JSON report.

Some rules list two severities

A rule can report at different severities depending on what it finds. When it does, the severity column lists every value it can emit.

datapackage/digest reads warning / error: a missing digest file only falls short of a SHOULD, so it is a warning; a file that is present but whose hash does not match may mean the archive was altered, so that is an error. Same rule, different finding, different treatment.

Any rule whose severity column lists more than one value is like this.

MUST, MUST NOT, SHOULD, SHOULD NOT and MAY carry their RFC 2119 meanings. The conformance column is copied from the specification, not wacz-validator’s own grading of how much a rule matters.

Where the sources stand

Only Data Package says so outright — each of its specification files opens with “the key words … are to be interpreted as described in RFC 2119”. WACZ 1.1.1 and 1.2.0, wacz-auth 0.1.0 and WARC 1.1 use MUST and SHOULD without ever citing RFC 2119 — checked: the string does not appear in any of them.

wacz-validator therefore reads every conformance level it records as RFC 2119 intends, whichever specification it came from. That follows the convention, but where a source does not say so, it is wacz-validator’s reading rather than the source’s statement.

The severity column carries the per-profile values

The first line of the severity column is the default (--profile spec); the smaller lines under it are the per-profile overrides. A rule with nothing underneath reports the first line everywhere.

Not every finding from a rule necessarily moves, so a count is shown when more than one does. A line like browserhive: >=1.11.0 is a producer version range: name a version outside it (--profile browserhive@1.10.0) and the rule does not run, which the report records under skipped. Conformance never moves with the profile — it is what the spec says. See Profiles.

Every rule

Rule / spec	Severity (per profile)	Conformance
browserhive/axtree-shapeBrowserHive WACZ Profile §accessibility	errorbrowserhive: >=3.8.0	MUST
browserhive/behaviors-shapeBrowserHive WACZ Profile §behaviors	errorbrowserhive: >=8.6.0	MUST
browserhive/deny-enforcedBrowserHive WACZ Profile §urlPolicies	error	MUST
browserhive/dismissal-shapeBrowserHive WACZ Profile §dismissal	errorbrowserhive: >=8.5.0	MUST
browserhive/document-withheldBrowserHive WACZ Profile §document	error / warningbrowserhive: >=13.0.0	MUST
browserhive/policy-not-truncatedBrowserHive WACZ Profile §completeness	errorbrowserhive: >=12.2.0	MUST
browserhive/settings-shapeBrowserHive WACZ Profile §settings	errorbrowserhive: >=8.0.0	MUST
browserhive/settle-deadlineBrowserHive WACZ Profile §settle	warningbrowserhive: >=10.3.0	MAY
browserhive/settle-shapeBrowserHive WACZ Profile §settle	errorbrowserhive: >=10.3.0	MUST
browserhive/storage-inventoryBrowserHive WACZ Profile §storage	errorbrowserhive: >=6.0.0	MUST
browserhive/storage-shapeBrowserHive WACZ Profile §storage directory	errorbrowserhive: >=6.0.0	MUST
browserhive/tls-chainBrowserHive WACZ Profile §tls	error / info	MUST
browserhive/tls-sanBrowserHive WACZ Profile §tls	errorbrowserhive: >=3.7.0	MUST
browserhive/url-policiesBrowserHive WACZ Profile §URL and media type policies	errorbrowserhive: >=8.0.0	MUST
browserhive/window-shapeBrowserHive WACZ Profile §windows	error	MUST
cdxj/filename-archive-relativeWACZ §indexes	errorlenient: warning (2 件)	MUST
cdxj/index-not-gzippedWACZ §indexes	warningbrowserhive: error (2 件)lenient: info (2 件)	MAY
cdxj/index-recognised-by-wabacWACZ §indexes	error / warning	MUST
cdxj/index-valid-dataWACZ §indexes	error	MUST
cdxj/pages-mainpageWACZ §pages	warninglenient: info (2 件)	SHOULD
cdxj/warc-offsetsWACZ §indexes	errorlenient: warning (3 件)	MUST
datapackage/digestWACZ §datapackage-digest.json	warning / errorlenient: info	SHOULD
datapackage/frictionless-schemaFrictionless Data Package	warning	SHOULD
datapackage/frictionless-structureFrictionless Data Package §requiredFrictionless Data Resource	error	MUST
datapackage/profile-requiredWACZ §datapackage.jsonFrictionless Data Package	error	MUST
datapackage/resource-hashesWACZ §datapackage.jsonFrictionless Data Resource	error	MUST
datapackage/resources-completeWACZ §datapackage.json	warninglenient: info	MUST
datapackage/wacz-version-requiredWACZ §datapackage.json	error / warninglenient: warning (2 件)	MUST
pages/page-schemaWACZ §pages	warninglenient: info (2 件)	MUST
wacz-auth/signaturewacz-auth 0.1.0 §Domain-Ownership Identity	error / info	MUST
wacz/required-filesWACZ §directories-and-files	error	MUST
wacz/reserved-dirs-cleanWACZ §directories-and-files	warninglenient: info	MUST NOT
warc/extension-gzip-matchWACZ §archive	warninglenient: info (2 件)	MUST
warc/members-independentWARC 1.1	error	MUST
warc/payload-digestWARC 1.1	info / warning	SHOULD
warc/recording-completeWARC 1.1 metadata record	warning / infobrowserhive: >=1.11.0	MAY
warc/storage-storeWACZ §archive	warninglenient: info	SHOULD

What the rules are grounded in

Rules fall into groups by the layer they inspect:

• wacz/* — the ZIP layout itself: which files and directories must exist, and what must not be in the reserved ones.
• datapackage/* — datapackage.json: the Frictionless structure, the declared profile, the WACZ version, and whether the hashes match what is actually in the archive.
• cdxj/* — the index: whether wabac.js can load it, whether its offsets point at real WARC records, and whether the filenames are archive-relative.
• warc/* — inside the WARC: independently-decodable gzip members, payload digests, and whether the recording is complete.
• pages/* — pages/pages.jsonl against its schema.

Why some rules exist twice over

Two rules can look at the same file for different reasons, and that is deliberate. wacz/required-files asserts that an index simply exists; cdxj/index-recognised-by-wabac asserts that wabac.js can actually load it. An archive can pass the first and fail the second, and the distinction is what tells a producer where the problem is.

Likewise wacz/required-files owns the “is datapackage.json there at all” question, so datapackage/profile-required can concentrate on the value of profile without reporting the same absence twice.

Adding a rule

A rule is a file under packages/core/src/validate/rules/ and an entry in that directory’s index.ts. Both steps are required: an unregistered rule never runs. The docs build counts the two and fails if they disagree, so a forgotten registration cannot ship quietly.