unpack-config: Extracting Embedded Document Bytes

To turn on byte extraction for every document the pipeline processes, set parseMode to UNPACK in the pipes section of your tika-config.json. That’s the minimum configuration — extraction defaults are fine for most cases.

To tune extraction (size limits, naming, ZIP output, etc.), add an unpack-config block under the top-level parse-context section. All the options listed below live inside that block:

This extracts both metadata (like RMETA mode) and embedded document bytes. Since 4.2 the output is a Frictionless Data Package on every surface, one <key>-frictionless.zip per container unless outputMode is DIRECTORY; "outputFormat": "REGULAR" restores the pre-4.2 flat layout.

All options below are fields of the unpack-config block — nest them inside parse-context.unpack-config as shown in the Quick Start.

maxUnpackBytes bounds zip bombs and other files that expand to enormous sizes. The 10 GiB default suits most corpora; lower it for untrusted input.

Hitting the limit is silent apart from a log line. The embedded file being written is truncated at the remaining budget, each later embedded file is skipped, and each case logs a WARN — but nothing is stamped on the metadata and the result status is unchanged (PARSE_SUCCESS / EMIT_SUCCESS). Watch the log, not the status, for truncation.

maxUnpackBytes: -1 (or any negative value) disables the limit — not recommended for untrusted input. 0 is not "unlimited": it caps extraction at zero bytes.

The UNPACK mode can output files in Frictionless Data Package format, a standard for packaging data files with their metadata. This format includes a datapackage.json manifest with file checksums and MIME types, making it easy to verify and process extracted files.

It is the default since 4.2 (TIKA-4681); 4.0 and 4.1 emitted the flat REGULAR layout unless outputFormat said otherwise. To get that layout back:

The five knobs interact differently per surface. Two defaults changed since 4.0.0: a Frictionless package carries rmeta.json unless includeMetadata is false (4.0.0 left it out unless includeFullMetadata was true), and since 4.2 Frictionless is the format on every surface. REGULAR’s layout is as it was; since 4.2 each .metadata.json sidecar is the file’s row from the metadata list, so it gets the metadata filters and text inference as rmeta.json does, and a row a filter removes gets no sidecar. Before 4.2 the package’s rmeta.json was named metadata.json, was not listed in datapackage.json, and did not get the metadata filters.

A document with nothing to unpack is still a package: datapackage.json and rmeta.json, with rmeta.json its only resource and no unpacked/. /unpack returns it with 200 rather than the 204 it gave before 4.2 (REGULAR output still gives 204). To get the 204 back, send "unpack-config": {"emptyPackage": "SKIP"} in the request’s config part.

/unpack/all means the source document’s bytes plus metadata in both formats. Under REGULAR that is where the per-file sidecars come from; under Frictionless rmeta.json is already there, so /all adds only the source document. outputMode: DIRECTORY is refused on /unpack: an HTTP response is one zip, so a request asking for it gets a 400, and a server whose own unpack-config says so fails at startup if the unpack endpoint is enabled — use /pipes or /async for per-file emission.

Output trees for doc.docx with three attachments:

For a single input file the output directory is the package; with no output directory tika-app writes to doc.docx-unpacked/ (REGULAR output too). For a directory of inputs each gets its own package under its relative path.

The package’s rmeta.json is the parse’s metadata list. On any surface, when the package goes to the container’s own emitter no separate <emitKey>.json is written; with includeMetadata: false the package is the bytes and the manifest, and no metadata is written at all. With emptyPackage: SKIP, a document with nothing to unpack writes nothing. A package sent to a different emitter than the container’s leaves the container’s metadata emit as it was.

The datapackage.json file contains:

The package passes frictionless validate:

One thing the validator reports that is not a manifest problem: it decompresses resources whose extension says .zip or .gz, so a corrupt or truncated embedded archive shows up as a compression-error. The manifest is still valid; the file is what it is.

For working code examples, see:

These test files demonstrate all configuration options with assertions.