Rules

wacz-validator は固定された rule の集合を archive に対して実行し、違反 1 件につき issue を 1 件報告します。全 rule の表は rule 定義そのものから生成して いるので、コードから遅れることがありません。rule 名・severity・適合レベル・profile ごとの上書き・spec リンクはすべて packages/core/src/validate/ 由来です。

表の読み方

適合レベルは spec が要求する強さ(MUST / SHOULD / MAY / MUST NOT)、 severity は違反に対して wacz-validator が取る扱いです。

severity は error / warning / info の 3 値です。判定に効くのは error だけで、 アーカイブが使えるかどうかは summary.failed(= error の件数)が 0 かで決まります —— warning と info は何件あっても覆しません。

severity	意味	summary.failed
error	これがあると使えない(再生が壊れる / 検証が成立しない)	増やす
warning	直すべきだが、それだけでは壊れない	変えない
info	観察の記録。良し悪しの判断を含まない	変えない

MUST / MUST NOT / SHOULD / SHOULD NOT / MAY は RFC 2119 の意味で用います。 表に出る適合レベルは wacz-validator が付けた重要度ではなく、spec 側の記述を写したものです。

severity を決めるのは「そのアーカイブが使えるか」だけです。たとえば datapackage/resources-complete は MUST ですが warning です — resources[] が不完全でも、それだけで replay が壊れるわけでは ないからです。

仕様準拠の観点で絞りたいときは適合レベルを見ます。 2 つの軸を別々に扱う方法は JSON レポートにあります。

severity 欄が 2 つ並ぶことがあります

1 つの rule が、見つけたものによって別の severity を出すことがあります。その場合 severity 欄には出しうる値がすべて並びます。

datapackage/digest は warning / error です — digest ファイルが 無いのは仕様上 SHOULD 未達なので warning、ファイルはあるのに hash が合わないのは アーカイブが変更された可能性を意味するので error。同じ rule でも、見つけたものが 違えば扱いも違います。

severity 欄に値が 2 つ以上並んでいる rule が、これに当たります。

出典側の事情

明示的に RFC 2119 を宣言しているのは Data Package だけです （各仕様書の冒頭に「本文書のキーワードは RFC 2119 に記述されたとおりに解釈される」とある）。 WACZ 1.1.1 / 1.2.0・wacz-auth 0.1.0・WARC 1.1 は MUST や SHOULD を使いながら、 RFC 2119 への言及がありません（本文中に一度も現れないことを確認済み）。

そこで wacz-validator は、どの仕様に由来する適合レベルでも RFC 2119 の意味で扱います。 慣例に従った解釈であり、出典側が明示していない部分については wacz-validator の側の取り決めです。

severity 欄には profile 別の値がぶら下がります

severity 欄の 1 行目が既定 (--profile spec) の値で、その下に字下げして並ぶのが profile 別の上書きです。下に何も無い rule は、どの profile でも 1 行目のまま報告されます。

その rule の指摘が全部変わるとは限らないので、複数が対象なら件数を添えています。 browserhive: >=1.11.0 のようにバージョンの範囲が出る rule は、その範囲外を --profile browserhive@1.10.0 のように名乗った実行では走らず、 落としたことが JSON の skipped に残ります。適合レベルは profile では動きません —— spec がそう書いている、という事実だからです。 プロファイルを参照。

全 rule

Rule / 出典	severity (profile 別)	適合レベル
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

rule が見ている層

• wacz/* — ZIP file の構造そのもの。存在しなければならないファイル / ディレクトリと、予約ディレクトリに異物が無いか。
• datapackage/* — datapackage.json。Frictionless の構造、宣言された profile、WACZ version、そして hash が実体と一致するか。
• cdxj/* — index。wabac.js がロードできるか、offset が実在の WARC record を指すか、filename が archive/ 相対か。
• warc/* — WARC の内部。gzip member が独立して展開できるか、payload digest、 recording が完結しているか。
• pages/* — pages/pages.jsonl の schema 適合。

同じファイルを 2 つの rule が見る理由

観点が違うので意図的にそうしています。wacz/required-files は index が 存在するかを assert し、cdxj/index-recognised-by-wabac は wabac.js が実際に ロードできるかを assert します。前者を通って後者で落ちる archive はあり得て、 その区別こそが producer に問題の所在を教えます。

同様に datapackage.json の存在チェックは wacz/required-files が担うので、 datapackage/profile-required は profile の値に専念できます(不在を 二重に報告しません)。

rule を追加するとき

rule は packages/core/src/validate/rules/ にファイルを置き、かつ同ディレクトリの index.ts に登録して初めて有効になります。両方が必要で、登録し忘れた rule は 一度も実行されません。docs のビルドが両者の件数を突き合わせるので、 登録忘れが静かに紛れ込むことはありません。