Web Archive Collection Zipped (WACZ)

WACZ は、ウェブアーカイブの collections を 1 つの独立したファイルとして packaged し、ウェブ上で共有できるようにする media type です。 WACZ ファイルには、アーカイブされたコンテンツの描画に必要なすべてのデータに加え、利用者がそれを解釈するために必要な contextual information が含まれます。描画ソフトウェアはこのデータを HTTP Range リクエストで必要に応じて取得でき、ファイル全体を取得することも、専用のサーバーサイドソフトウェアを介することも要しません。

> **非公式翻訳 (Unofficial translation).** これは WACZ 1.1.1 仕様の有志による日本語訳です。 > 正典は英語原典 [specs.webrecorder.net/wacz/1.1.1](https://specs.webrecorder.net/wacz/1.1.1/) 。 > 原著作: Webrecorder, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)。 > 本訳は原文を翻訳・改変したもので、Webrecorder の公認・推奨を示すものではありません。 ## Status of This Document これは WACZ 標準の安定版であり、Webrecorder プロジェクトで実際に使用されています。質問や提案は [GitHub issues](https://github.com/webrecorder/specs/issues/) を開いてください。 ## Terminology この節では、本仕様およびウェブアーカイブ基盤全体で用いられる用語を定義する。これらの用語が本仕様中に現れるたびに、その定義へのリンクが付与される。

Collection: トピック・ウェブサイトのドメイン・期間など、何らかの概念的なまとまりに基づく、関連するアーカイブ済みウェブページとメタデータの任意の集合。
Context: あるウェブアーカイブに関する説明的な情報で、そのアーカイブを利用する人がアーカイブの内容を理解・解釈する助けとなるもの。この情報には、なぜそのコンテンツがアーカイブ対象として選ばれたか、いつ作成されたか、誰が作成したか、どのツールやアプリケーションを用いて作成したか、などが含まれうる。
IIPC: 国際インターネット保存コンソーシアム (International Internet Preservation Consortium)。ウェブコンテンツを保存する取り組みを調整するため 2003 年に設立された、図書館・アーカイブ機関などの組織。
Media Type: World Wide Web とその基盤であるインターネット上で転送されるファイル形式のための、2 部構成の識別子。[[IANA-MEDIA-TYPES]]。
Package: 個別のファイルやビットストリームを内部に表現できるファイル形式。代表的なパッケージ形式の例として ZIP・PDF・MP4・tar・Open Office XML がある。
Page: 特定の URL を表示しているウェブブラウザで閲覧される web ドキュメント。web page と呼ばれることもある。
WACZ: Web Archive Collection Zipped。本仕様に準拠したファイルで、WARC データとメタデータを ZIP ファイルにパッケージ化し、ウェブ上での配布とリプレイに用いる。
WARC: [[WARC]] 仕様に準拠した、ウェブリソースの表現を連結して格納したファイル。
Wayback Machine: アーカイブ済みウェブページをリプレイするための著名なウェブアプリケーション。当初 Internet Archive で開発され、IIPC によってオープンソースアプリケーションとして fork された。
Web Archive: ウェブリソースの表現を WARC 形式で保存するファイルの集合。ウェブアーカイブには、アーカイブ内のレコードへアクセスするための CDX インデックスなどの派生ファイルが含まれることもある。
ZIP file: [[ZIP]] 仕様に準拠したファイルで、複数のファイルを単一の相互運用可能なコンテナに集約・圧縮・暗号化するために用いられる。WACZ は、より大きなアーカイブのために ZIP と ZIP64 の両エンコーディングを許容する。

## Introduction 本仕様は、web archives を共有・配布するためのディレクトリ構造と ZIP 形式の仕様を定義する。この形式を用いた ZIP ファイルは WACZ(Web Archive Collection Zipped)と呼ぶことができる。 ### Motivation 本仕様の目標は、web archives のための可搬な形式を提供し、ウェブアーカイブに関する 2 つの大きな目標を達成することである: 1. *Social*: ウェブアーカイブの collections を、利用者がそれらを解釈し意味のある形で操作するために必要な contextual information とともに、相互運用可能な方法で共有する手段を提供すること。 2. *Technical*: 静的ストレージ上にリモートホストされたファイルから *少量のデータ* を動的に読み込む効率的な手段を、ファイル全体のダウンロードや専用のサーバーサイドアプリケーションの介在を必要とせずに提供すること。ウェブアーカイブコレクションを利用し理解するには、アーカイブされたウェブコンテンツに加え、そのコレクションが何を含み、いつ・どのように作成されたかを記述する contextual information が必要である。また、コレクションを閲覧するための入口となる pages の集合も必要となる。これらのデータはすべて一緒に packaged される必要がある。そうすることで、各部分を誤って分離させることなく容易にコピー・転送できる。このデータパッケージは、あるストレージシステムから別のシステムへ容易に移送でき、電子メールの添付として送れ、USB メモリに入れられ、そして(クラウドオブジェクトストレージや CDN から) 指定された URL で静的ドキュメントとして配信するだけでホストできる必要がある。現在、ウェブアーカイブをホストするには、ブラウザで閲覧できる形で WARC データを配信するための複雑なサーバーインフラ(例: Wayback Machine)が必要である。WACZ 形式は、packaged された WARC データへの効率的なランダムアクセスに最適化されたストレージ手法を提供し、ブラウザが特定のページに必要なものだけを取得してそのページを描画できるようにする。これは、ウェブアーカイブの内容とそれを構成するメタデータの位置特定に ZIP 形式の組み込みインデックスを活用することで実現される。 WACZ は他のウェブアーカイブ形式を置き換えることを意図したものではない。むしろ、ウェブアーカイブコレクションの効率的な描画とその文脈付けのためにブラウザが必要とするすべてのデータについて、ファイルの packaging 規約を定めるものである。 ### Existing Tools [py-wacz](https://github.com/webrecorder/py-wacz) リポジトリには、既存の WARC ファイルから WACZ ファイルを作成し、それらを検証するためのリファレンス実装が含まれている。本仕様の一部は [wabac.js](https://github.com/webrecorder/wabac.js) および [ReplayWeb.page](https://replayweb.page) でも実装・利用されている。 ## WACZ Object WACZ オブジェクトは次のものから構成される: 1. [[FRICTIONLESS-DATA-PACKAGE]] で規定される技術的・記述的メタデータを記録するための `datapackage.json` ファイル。 2. web archive データのための、拡張可能なディレクトリおよび命名規約。 3. そのディレクトリ構成を ZIP ファイルにまとめる方法。 ### Directory Layout WACZ はディレクトリ構造を含み、その中にウェブアーカイブコレクションのデータを格納する。このデータは [[FRICTIONLESS-DATA-PACKAGE]] 仕様に準拠しなければならない (MUST)。このディレクトリ構造は次のようになる:

├── archive
│   └── data.warc.gz
├── datapackage.json
├── datapackage-digest.json
├── indexes
│   └── index.cdx.gz
└── pages
    └── pages.jsonl

### Directories and Files #### archive `archive` ディレクトリは [[WARC]] 形式のファイルを 1 つ以上含まなければならない (MUST)。これらのファイルは、GZIP エンコードされていない限り `.warc` 拡張子を使うべきである (SHOULD)。GZIP エンコードされている場合は `.warc.gz` 拡張子を使わなければならない (MUST)。

archive
└── data.warc

#### indexes `indexes` ディレクトリは、`archive` に格納された WARC データに対するインデックスを 1 つ以上含まなければならない (MUST)。これらのインデックスファイルにより、クライアントは URL が WACZ に含まれるかどうかを効率的に検索できる。インデックスファイルは CDXJ データを含まなければならず (MUST)、gzip 圧縮されてもよい (MAY) [[PYWB-CDXJ]]。

indexes
└── index.cdx.gz

#### pages.jsonl `pages/pages.jsonl` は存在しなければならず (MUST)、'Page' オブジェクトのリストを [[JSON-Lines]] として含む。各行は少なくとも次のプロパティを含まなければならない (MUST): - `url` - ページの URL - `ts` - [[RFC3339]] の日時文字列 [[JSONL]] ファイルの各エントリは、ウェブアーカイブコレクションのナビゲーションを助けるために次のプロパティを含んでもよい (MAY): - `title` - リソースを説明する文字列 - `id` - リソースの任意の識別子 - `text` - スナップショットから抽出したテキスト - `size` - ページとそのすべてのリソースのバイト数を表す整数

{"format": "json-pages-1.0", "id": "pages", "title": "All Pages"}
{"id": "1db0ef709a", "url": "https://www.example.com/page", "size": 1256, "ts": "2020-10-07T21:22:36Z", "title": "Example Domain", "text": "Example Domain This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission. More information..."}
{"id": "12304e6ba9", "url": "https://www.example.com/another", "size": 1256, "ts": "2020-10-07T21:23:36Z", "title": "Another Page", "text": "Example Domain This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission. More information..."}

[[JSONL]] ファイルの各エントリは、必須プロパティに干渉しない限り、追加のプロパティを含んでもよい (MAY)。同じ形式の他の [[JSONL]] ファイルを `pages/` ディレクトリに追加してもよい (MAY)。よくある使い方は、`pages.jsonl` にはメインのページだけを含め、クロールによって自動的に発見されたページなどの追加ページは別のファイル(例: `extraPages.jsonl`)に含める、というものである。 #### datapackage.json `datapackage.json` ファイルは WACZ のルートに存在しなければならず (MUST)、ウェブアーカイブのマニフェストとして機能し、[[FRICTIONLESS-DATA-PACKAGE]] 仕様に準拠する。次のプロパティを含まなければならない (MUST): - `profile`: 文字列 `data-package` - `resources`: WACZ に含まれるすべてのファイルの、ファイル名・パス・サイズ・フィクシティ (fixity) のリスト。 - `wacz_version`: 使用した WACZ のバージョン(例: `1.1.1`)

{
  "profile": "data-package",
  "wacz_version": "1.1.1",
  "resources": [
     {
       "name": "pages.jsonl",
       "path": "pages/pages.jsonl",
       "hash": "sha256:8a7fc0d302700bed02294404a627ddbbf0e35487565b1c6181c729dff8d2fff6",
       "bytes": 75
     },
     {
       "name": "data.warc",
       "path": "archive/data.warc",
       "hash": "sha256:0e7101316ba5d4b66f86a371ee615fbd20f9d3f32d32563ed2c829db062f7714",
       "bytes": 11469796
     }
  ]
}

`datapackage.json` は、描画アプリケーションが利用者にウェブアーカイブに関する contextual information を提示できるよう、次のプロパティを含むべきである (SHOULD): - `title`: コレクションの文字列または 1 文の説明 - `description`: アーカイブの内容についてのより長い説明。 Markdown 形式でなければならない (MUST)(プレーンテキストも妥当な Markdown である) - `created`: WACZ ファイルが作成された日時([[RFC3339]]) - `modified`: WACZ ファイルが最後に変更された日時([[RFC3339]]) - `software`: WACZ ファイルの作成に使われたソフトウェアの説明 - `mainPageUrl`: 初期リプレイに用いる、コレクションのメインまたは開始ページの任意の URL - `mainPageDate`: 初期リプレイに用いる、コレクションのメインまたは開始ページの任意の ISO 形式の日付 [[FRICTIONLESS-DATA-PACKAGE]] 仕様の他のプロパティ(`licenses`・`version`・ `organization`・`contributors`・`email` など)を使ってもよい (MAY)。既存のプロパティに干渉しないカスタムプロパティを使ってもよい (MAY)。 #### datapackage-digest.json `datapackage-digest.json` ファイルは、`datapackage.json` マニフェストをハッシュで検証し、ひいては WACZ 全体の内容を検証するために、WACZ のルートに含めるべきである (SHOULD)。存在する場合は次のプロパティを含まなければならない (MUST): * `path`: 文字列 "datapackage.json" * `hash`: `datapackage.json` ファイルの暗号学的ハッシュ

{
  "path": "datapackage.json",
  "hash": "sha256:ec1f44ab13e2c94b0ddf66e9673d585ba4a77e6f8c9cc30d8665da434557e885"
}

WACZ の作成者性 (authorship) を主張・証明するために `datapackage-digest.json` に暗号学的署名を記録する方法については、[WACZ Signing and Verification](../../wacz-auth/latest/) を参照のこと。 ### Other files and directories WACZ には、WACZ が使用する指定済みのファイルやディレクトリに干渉しない限り、その他のファイルやディレクトリが存在してもよい (MAY)。特に、既存の WACZ ディレクトリ `archive`・`indexes`・`pages` にカスタムのファイルやディレクトリを追加してはならない (MUST NOT)。追加のファイルは、[[FRICTIONLESS-DATA-PACKAGE]] への準拠を保証するため、 `datapackage.json` の resources セクションに列挙しなければならない (MUST) ### Zip Format ディレクトリ構造全体は、標準的な [[ZIP]] ファイルに格納しなければならない (MUST)。 #### Zip Compression ランダムアクセスを可能にするため、すでに圧縮されているファイルを再度圧縮してはならない (MUST NOT)。 - すべての `archive/` ファイルは、ZIP の 'STORE' モードで格納すべきである。 - すべての `index/*.cdx.gz` ファイルは、ZIP の 'STORE' モードで格納すべきである。 - すべてのファイル(`*.jsonl`・`*.json`・`*.idx`・`*.cdx`・`*.cdxj`)は、ZIP の 'DEFLATE' または 'STORE' のいずれかのモードで格納できる。 #### Zip Format File Extension この Web Archive Collection 形式仕様に従う ZIP ファイルは、拡張子 `.wacz` を使わなければならない (MUST)。そのようなファイルは WACZ ファイルまたは WACZ と呼ぶことができる。 ## Processing Model [[ZIP]] ファイル形式は効率的なランダムアクセスを提供する。これは、大きなウェブアーカイブコレクションからでも、WACZ 全体を転送することなくアーカイブ済みウェブページを効率的に取得できることを意味する。これを実現するため、WACZ クライアントは HTTP RANGE リクエスト [[RFC7233]] を用いて ZIP ファイルの一部を必要に応じて読み取ることができる。処理モデルは次のように働く。ZIP ファイルが与えられると、クライアントは素早く: 1. すべてのエントリを読んで ZIP ファイルの内容を把握する 2. `datapackage.json` からコレクションのメタデータを読み込む 3. もしあれば `pages.jsonl` からページのリストを読み込む特定の URL を検索するには、クライアントは次を行う必要がある: 1. ZIP から CDX 全体を読む 2. インデックスを二分探索して URL を探す 3. 一致が見つかれば、WARC 内のオフセット/長さ/位置を得る 4. ZIP 内の圧縮された WARC チャンクを読むこのアプローチは [ReplayWeb.page](https://replayweb.page) で使われている ## Publishing WACZ は ZIP ファイルであるため、静的ファイルとしてウェブ上にホストできる。これにより、広く利用可能でオープンソースかつ十分にテストされたウェブサーバーアプリケーション以外の複雑なサーバーサイドソフトウェアに頼ることなく、ウェブアーカイブを長期にわたって容易に維持できる。必要であれば、クラウドホスティング事業者が提供する HTTP オブジェクトストアや、ウェブアーカイブを地理的に利用者に近づけるコンテンツデリバリネットワークを用いて、WACZ ファイルを管理しアクセス可能にできる。ただし、 WACZ ファイルを公開する際にはいくつか考慮すべき点がある。 ### Content-Length WACZ クライアントは、描画前にダウンロードする、あるいは動的に読み取るために、 WACZ ファイル全体の大きさを知る必要がある。これをサポートするため、WACZ ファイルに対する HTTP 応答は `Content-Length` HTTP ヘッダーを使わなければならない (MUST)。 ### Partial Requests WACZ ファイルを描画するクライアントは、通常、WACZ ファイルからコンテンツを必要に応じて取得できる必要がある。例えば、特定の URL に対するアーカイブ済みコンテンツを表示する際には、その URL を CDXJ インデックスで検索し、インデックスエントリのバイトオフセットを用いて、WACZ に内包された特定の WARC ファイルの一部を取得する。クライアントがこの動的な取得を行えるようにするため、WACZ ファイルを公開するウェブサーバーは HTTP range リクエスト [[RFC7233]] をサポートしなければならない (MUST)。WACZ への HTTP 応答は、`Accept-Ranges` HTTP ヘッダーを用いて WACZ ファイルを配信すべきである (SHOULD)。 ### CORS WACZ ファイルとそのクライアントは、同じホスト名から配信されてもよい (MAY)。しかし、 WACZ ファイルを公開しているホスト名とは異なるホスト名からウェブアーカイブを閲覧できると便利な場合がある。例えば、クラウド事業者の HTTP オブジェクトストレージ (例: `s3.amazonaws.com`)を用いて WACZ ファイルを公開し、別のドメイン(例: `example.org`)で閲覧可能にする場合がそれにあたる。また、WACZ の公開者が自分のウェブアーカイブをウェブ上で流通させ、複数の場所で閲覧可能にしたい場合もそうである。セキュリティ上の理由から、ブラウザは、読み込もうとしているウェブサイトとは異なるドメインにホストされたファイルへのアクセスを制限する。異なるドメインからの読み込みをサポートするため、WACZ ファイルは `access-control-allow-origin` [[CORS]] HTTP ヘッダーを用いて利用可能にすべきである (SHOULD)。 ### Media Type WACZ ファイルに対する WACZ の HTTP 応答は、`application/wacz` メディアタイプで公開すべきである (SHOULD)。 ### Example Response これらの要件を踏まえると、WACZ に対する最小の HTTP 応答は次のようになりうる:

HTTP/2 200
Content-Type: application/wacz
Content-Length: 20961755
Accept-Ranges: bytes
Access-Control-Allow-Origin: *