# How to Get Detailed PDF Analysis with JSON Output from detect-pdf

> Get detailed PDF analysis with JSON output using detect-pdf. Use --json and --analyze flags to extract structured data and layout metadata like tables and columns.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Use the `--json` flag to emit structured detection results, and add `--analyze` to include layout metadata such as tables and columns in the JSON output.**

The `detect-pdf` CLI tool in the firecrawl/pdf-inspector repository provides a fast, programmatic way to classify PDF documents and extract structural metadata. By combining specific command-line flags, you can generate deterministic JSON reports that detail page types, OCR requirements, and complex layout features without writing custom parsing code.

## Understanding the detect-pdf CLI Architecture

The `detect-pdf` binary, defined in [`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs), serves as a lightweight wrapper around the core inspection library. It exposes two primary operational modes that determine the depth of analysis performed before serialization.

When you invoke the tool without flags, it runs `run_detect_only` (lines 29-43 in [`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs)), which calls `detect_pdf_type()` to return a `DetectionResult` containing basic classification data. Adding the `--analyze` flag triggers `run_analyze` (lines 45-64), which executes `process_pdf_with_options()` with `ProcessMode::Analyze` to perform full layout extraction including table and column detection.

## Generating Basic JSON Output

To receive a compact JSON summary instead of the default human-readable report, append the `--json` flag to your command. This flag instructs the binary to manually construct the response using internal helper functions like `json_escape` and `format_ocr_reasons_by_page` rather than relying on external serialization libraries.

```bash
detect-pdf my-document.pdf --json

```

Typical output structure:

```json
{
  "pdf_type":"scanned",
  "page_count":12,
  "pages_sampled":5,
  "pages_with_text":0,
  "confidence":0.95,
  "title":"My PDF Title",
  "ocr_recommended":true,
  "pages_needing_ocr":[1,2,3,4,5,6,7,8,9,10,11,12],
  "ocr_reasons_by_page":[
    {"page":1,"reasons":["no extractable text"]},
    {"page":2,"reasons":["low text density"]}
  ],
  "detection_time_ms":84
}

```

The `ocr_reasons_by_page` array is formatted by the `format_ocr_reasons_by_page` helper (lines 29-43), which safely escapes strings to ensure valid JSON output.

## Enabling Detailed Layout Analysis

For applications requiring structural metadata—such as identifying tabular data or multi-column layouts—combine the `--json` and `--analyze` flags. This configuration runs the full extraction pipeline via `process_pdf_with_options()` before reporting, populating additional fields in the JSON output.

```bash
detect-pdf my-document.pdf --json --analyze

```

Extended output includes layout-specific fields:

```json
{
  "pdf_type":"mixed",
  "page_count":30,
  "pages_needing_ocr":[7,14,21],
  "ocr_reasons_by_page":[
    {"page":7,"reasons":["image‑only region"]},
    {"page":14,"reasons":["low text density"]},
    {"page":21,"reasons":["mixed content"]}
  ],
  "is_complex":true,
  "pages_with_tables":[5,12,19],
  "pages_with_columns":[3,8,15],
  "detection_time_ms":212
}

```

According to the source code in [`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs) (lines 45-64), the `--analyze` flag invokes `run_analyze()`, which calls `process_pdf_with_options(pdf_path, PdfOptions::new().mode(ProcessMode::Analyze))` to extract the `pages_with_tables` and `pages_with_columns` vectors from the `ProcessResult` structure.

## Understanding the JSON Schema

### Basic Detection Fields

The core `DetectionResult` struct—returned by `detect_pdf_type()` in [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs)—serializes the following fields to JSON:

- **pdf_type**: Classification as "scanned", "text", or "mixed"
- **confidence**: Float value between 0.0 and 1.0 indicating detection certainty
- **pages_needing_ocr**: Array of page numbers requiring optical character recognition
- **ocr_reasons_by_page**: Per-page explanations for OCR recommendations
- **title**: Extracted document metadata (when available)

### Extended Analysis Fields

When `--analyze` is specified, the tool augments the base detection with data from the `ProcessResult` structure:

- **is_complex**: Boolean indicating multi-column or intricate layouts
- **pages_with_tables**: Array of page indices containing tabular structures (detected via logic in `src/tables/`)
- **pages_with_columns**: Array of page indices with columnar text layouts
- **detection_time_ms**: Total processing time including layout analysis

## Using the Rust API for Custom Workflows

While the CLI provides convenient JSON serialization, you can access the same detection and analysis capabilities programmatically through the library interface defined in [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs).

```rust
use pdf_inspector::{detect_pdf_type, process_pdf_with_options, PdfOptions, ProcessMode};

fn main() -> Result<(), pdf_inspector::PdfError> {
    // Simple detection
    let det = detect_pdf_type("my-document.pdf")?;
    println!("Detected type: {}", det.pdf_type);

    // Full analysis
    let res = process_pdf_with_options(
        "my-document.pdf",
        PdfOptions::new().mode(ProcessMode::Analyze),
    )?;
    println!("Layout is complex? {}", res.layout.is_complex);
    Ok(())
}

```

The `PdfOptions` and `ProcessMode` enums, defined in [`src/process_mode.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/process_mode.rs), control which extraction stages execute. Setting `mode(ProcessMode::Analyze)` activates the same pipeline used by the CLI's `--analyze` flag.

## Summary

- Use **`--json`** to output machine-readable detection results instead of formatted text reports
- Add **`--analyze`** to include layout metadata like tables and columns in the JSON output
- The CLI manually constructs JSON strings to avoid external serializer dependencies, ensuring deterministic output
- Underlying functionality relies on `detect_pdf_type()` for basic classification and `process_pdf_with_options()` for full layout analysis
- Key source files include [`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs) (CLI logic), [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs) (core detection), and [`src/process_mode.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/process_mode.rs) (analysis configuration)

## Frequently Asked Questions

### What is the difference between basic detection and full analysis in detect-pdf?

Basic detection, triggered without flags or with only `--json`, executes `detect_pdf_type()` to classify the PDF and determine OCR requirements. Full analysis, enabled by `--analyze`, runs `process_pdf_with_options()` with `ProcessMode::Analyze` to extract structural elements like tables and columns, adding these fields to the JSON output.

### How does detect-pdf handle JSON serialization without external dependencies?

The tool constructs JSON output manually through helper functions `json_escape`, `format_ocr_reasons_by_page`, and `format_detector_ocr_reasons` within [`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs). This approach keeps the binary lightweight and ensures consistent, deterministic formatting without pulling in full-fledged serialization libraries.

### Can I use detect-pdf programmatically outside of the CLI?

Yes. The firecrawl/pdf-inspector library exposes public APIs in [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) including `detect_pdf_type()` and `process_pdf_with_options()`. You can import the crate into your Rust application and configure analysis options using `PdfOptions::new().mode(ProcessMode::Analyze)` to replicate CLI behavior programmatically.

### What determines if a page needs OCR according to the detector?

The detection logic in [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs) evaluates text density, extractability, and content type. Pages are flagged for OCR if they contain no extractable text, exhibit low text density, or contain image-only regions. The `ocr_reasons_by_page` field in the JSON output provides specific justification for each flagged page.