Serialization and Configuration

Tika 4.x uses JSON-based configuration and serialization throughout the system. This document explains how the serialization system works and how to create components that integrate with it.

Overview

Tika’s serialization system provides:

  • JSON Configuration: Configure Tika components using JSON files

  • Friendly Names: Reference components by name (e.g., pdf-parser) instead of class names

  • ParseContext Serialization: Send per-request configuration via FetchEmitTuple

  • Security: Only registered components can be instantiated from JSON

The system is built on Jackson with custom serializers/deserializers in the tika-serialization module.

JSON Configuration Format

Tika uses a compact format for component configuration:

{
  "auto-detect-parser": {
    "throwOnZeroBytes": false
  },
  "parse-context": {
    "commons-digester-factory": {
      "digests": [
        { "algorithm": "MD5" },
        { "algorithm": "SHA256" }
      ]
    }
  }
}

Components can be specified as:

  • String: "pdf-parser" - creates instance with defaults

  • Object: {"pdf-parser": {"ocr": {"strategy": "AUTO"}}} - creates configured instance

The @TikaComponent Annotation

The @TikaComponent annotation is required for any class that should be configurable via JSON. It serves multiple purposes:

  1. Registration: Registers the class with a friendly name

  2. Index Generation: Creates lookup files for name-to-class resolution

  3. SPI Registration: Optionally registers for Java ServiceLoader

  4. Security: Acts as an allowlist for deserialization

Basic Usage

@TikaComponent
public class MyCustomParser implements Parser {
    // Parser implementation
}

This automatically:

  • Generates friendly name my-custom-parser from the class name

  • Adds to META-INF/tika/parsers.idx for name lookup

  • Adds to META-INF/services/org.apache.tika.parser.Parser for SPI

Annotation Attributes

Attribute Default Description

name

(auto-generated)

Custom friendly name instead of deriving from class name

spi

true

Whether to register in META-INF/services/ for ServiceLoader

contextKey

(auto-detected)

Class to use as ParseContext key (rarely needed)

defaultFor

(none)

Marks as default implementation for an interface

Example with Attributes

@TikaComponent(name = "my-parser", spi = false)
public class MyInternalParser implements Parser {
    // Not auto-discovered via SPI, but configurable via JSON
}

Context Key Detection

When storing components in ParseContext, Tika needs to know which class to use as the lookup key. For example, CommonsDigesterFactory should be retrievable via parseContext.get(DigesterFactory.class).

Automatic Detection

Tika automatically detects the context key by checking if your class implements one of these known interfaces:

  • Parser, Detector, EncodingDetector

  • MetadataFilter, Translator, Renderer

  • DigesterFactory, ContentHandlerFactory

  • EmbeddedDocumentExtractorFactory, MetadataWriteLimiterFactory

@TikaComponent
public class CommonsDigesterFactory implements DigesterFactory {
    // Context key automatically detected as DigesterFactory.class
}

Explicit Context Key

For interfaces not in the auto-detection list, specify explicitly:

@TikaComponent(contextKey = DocumentSelector.class)
public class SkipEmbeddedDocumentSelector implements DocumentSelector { }

Service Interface Categories

First-Class Service Interfaces

These are loaded via SPI and have dedicated index files:

Interface Index File

Parser

parsers.idx

Detector

detectors.idx

EncodingDetector

encoding-detectors.idx

LanguageDetector

language-detectors.idx

Translator

translators.idx

Renderer

renderers.idx

MetadataFilter

metadata-filters.idx

ParseContext Components

Components not implementing first-class interfaces go to parse-context.idx:

  • DigesterFactory - Digest/checksum calculation

  • ContentHandlerFactory - SAX content handler creation

  • EmbeddedDocumentExtractorFactory - Embedded document handling

  • MetadataWriteLimiterFactory - Metadata write limiting

Self-Configuring Components

Components implementing SelfConfiguring handle their own configuration at runtime rather than during initial loading:

@TikaComponent
public class PDFParser extends AbstractParser implements SelfConfiguring {

    private PDFParserConfig defaultConfig = new PDFParserConfig();

    @Override
    public void configure(ParseContext parseContext) {
        PDFParserConfig config = ParseContextConfig.getConfig(
            parseContext, "pdf-parser", PDFParserConfig.class, defaultConfig);
        // Use config...
    }
}

Benefits:

  • Per-request configuration via ParseContext

  • Lazy loading - config only parsed when needed

  • Merging with defaults handled automatically

ParseContext Serialization

ParseContext can be serialized to JSON for transmission (e.g., in FetchEmitTuple):

{
  "parse-context": {
    "pdf-parser": {
      "ocr": {
        "strategy": "AUTO"
      },
      "extractInlineImages": true
    },
    "commons-digester-factory": {
      "digests": [{"algorithm": "SHA256"}]
    }
  }
}

All entries use this flat, friendly-named form and are resolved lazily: a config is parsed into its component only when first needed (see resolveAll). There is no separate "immediate" or "typed" form.

Security Model

The serialization system implements a security allowlist:

  1. @TikaComponent Required: Only annotated classes are registered

  2. Registry Lookup: Deserialization only instantiates registered classes

  3. No Arbitrary Classes: Unknown class names cause errors, not instantiation

This prevents attacks where malicious JSON specifies dangerous classes for instantiation.

// This will FAIL - class not registered
{
  "parse-context": {
    "java.lang.Runtime": {}  // Error: Unknown component
  }
}

Untrusted (Wire) Input: Restricted Mode

Configuration files loaded at startup via TikaLoader are treated as trusted. Per-request configuration arriving over the wire — tika-server request bodies and pipes FetchEmitTuple`s — is deserialized in restricted mode (`ParseContextDeserializer.readParseContext(node, true)), which adds a second, fail-closed gate on top of the registry:

  • Only context-key types confined to shaping this request’s metadata or output may be instantiated from the wire: MetadataFilter, ContentHandlerFactory, ContentHandlerDecoratorFactory, DigesterFactory, MetadataWriteLimiterFactory, UnpackSelector

  • Types with exec/IO/network capability or control over which components run are blocked: Parser, Detector, EncodingDetector, Renderer, Translator, EmbeddedDocumentExtractorFactory

  • The check is fail-closed: a newly added context-key interface is blocked until it is consciously allow-listed

  • The whole tree is scanned before any component is constructed

The allowlist/blocklist lives in ComponentNameResolver (WIRE_INSTANTIABLE_CONTEXT_KEYS / WIRE_BLOCKED_CONTEXT_KEYS); an exhaustiveness test asserts every context-key interface is classified as exactly one of the two. Plain config DTOs (non-component keys) are never blocked.

Framework Directives

Some JSON keys are consumed by the loading framework itself rather than by the component whose config object they appear in. When such a directive shares a JSON object with a component’s own properties, it carries a leading underscore to avoid namespace collisions with legitimate component config keys:

{
  "parsers": [
    {
      "pdf-parser": {
        "_mime-include": ["application/pdf"],
        "_mime-exclude": ["application/pdf+fdf"],
        "extractInlineImages": true
      }
    }
  ]
}

_mime-include/_mime-exclude are stripped before the component sees its config and are applied by the framework as a MIME-filtering decorator around the parser. New framework directives must follow the underscore convention.

Marker entries that have no component-config namespace of their own are the exception: "exclude" on default-parser/default-detector/ default-encoding-detector needs no prefix because those markers carry only framework keys.

Creating a Custom Component

Complete example of a custom metadata filter:

package com.example.tika;

import org.apache.tika.config.TikaComponent;
import org.apache.tika.exception.TikaException;
import org.apache.tika.metadata.Metadata;
import org.apache.tika.metadata.filter.MetadataFilter;

@TikaComponent
public class UpperCaseFilter implements MetadataFilter {

    private String fieldName = "title";

    public void setFieldName(String fieldName) {
        this.fieldName = fieldName;
    }

    public String getFieldName() {
        return fieldName;
    }

    @Override
    public void filter(Metadata metadata) throws TikaException {
        String value = metadata.get(fieldName);
        if (value != null) {
            metadata.set(fieldName, value.toUpperCase());
        }
    }
}

Configure in JSON. Metadata filters are loaded via parse-context (they implement the MetadataFilter interface, which is a ParseContext-keyed component):

{
  "parse-context": {
    "upper-case-filter": {"fieldName": "dc:title"}
  }
}

Or with defaults (string form constructs with no overrides):

{
  "parse-context": {
    "upper-case-filter": {}
  }
}

Troubleshooting

"Unknown component name" Error

  • Ensure class has @TikaComponent annotation

  • Verify annotation processing ran during compilation

  • Check that META-INF/tika/*.idx file exists in JAR

Component Not Found in ParseContext

  • Verify you’re using the correct interface type for lookup

  • Check if explicit contextKey is needed

  • For self-configuring components, ensure configure() was called

SPI Not Loading Component

  • Check that spi = true (the default)

  • Verify META-INF/services/ file exists

  • Ensure JAR is on classpath