PDF Checker & PDF Optimizer: A JSON Workflow Guide

If you work with PDFs at any real volume — ingesting them from customers, archiving them for compliance, or preparing them for print and web delivery — you already know the two big problems: documents come in broken, and documents come in bloated. Datalogics builds a tool for each half of that problem, and both are controlled the same way: a plain-text JSON profile that tells the tool exactly what to look for or what to change. Once you understand the JSON profile pattern, you can drive both tools from the same mental model, and chain them into a single automated pipeline.

This guide walks through both tools, how their JSON profiles work, and how to combine them into a "check, then fix, then verify" workflow you can drop into a batch process or CI/CD pipeline.

Two Tools, One Pattern

PDF Checker is a free, command-line diagnostic tool. It doesn't change your PDFs — it inspects them and reports on structural corruption, unembedded fonts, invalid color spaces, disallowed content, and dozens of other conditions that could cause a document to fail downstream. When it finds corruption, it attempts an in-memory recovery so you can tell whether the file is still safely processable without ever touching the original.

PDF Optimizer is the tool you run once you know what's wrong. It's a command-line utility that reduces file size and fixes document issues through a configurable set of operations: image downsampling and recompression, color space conversion, transparency flattening, font subsetting, object removal, metadata stripping, linearization for fast web delivery, and conversion to PDF/A or PDF/X for archival and print compliance.

Both tools run on Windows (64-bit) and Linux (64-bit), and both are built on the same core engine as the Adobe PDF Library, so behavior is consistent across platforms and at high volume. And critically, every PDF Optimizer purchase includes PDF Checker at no additional cost — they're meant to be used as a pair.

The Shared Control Mechanism: JSON Profiles

Neither tool works off of generic defaults. Instead, each is driven by a JSON profile: a plain-text configuration file, written in JavaScript Object Notation, that spells out exactly which checks or operations to apply and how.

This shared design has a few practical benefits:

• Nothing happens unless you say so. In both tools, settings are optional and off by default. A profile can be a single setting or a comprehensive, fully-specified configuration.
• You configure once, reuse everywhere. Build a profile that matches your business rules, then apply it consistently across every document in a directory or pipeline.
• You can start small and grow. Begin with a minimal profile and add checks or operations incrementally as you learn what your document set actually needs.

JSON Profiles in PDF Checker

PDF Checker ships with a default profile called everything.json, which turns on every available check — a comprehensive baseline for a first pass over an unfamiliar document set. From there you have three options:

• Use everything.json as-is for a thorough scan.
• Edit a copy of it to narrow down to the checks you actually care about.
• Use it as a template to build an entirely new, purpose-built profile.

A typical setting looks like this, which checks for fonts that aren't embedded and flags the finding as an error:

"uses-fonts-not-embedded": {
  "check": "on",
  "report-as-error": "on",
  "report-message": "Document uses fonts not embedded in document"
}

A few practical tips when building custom profiles:

• Start from a copy, never the original. Duplicate everything.json and rename it before editing, so you always have the full-featured original to fall back on or reference later, and so a product update doesn't overwrite your customizations.
• Validate before you deploy. Run your profile through a JSON linter (JSONLint is a common choice) to catch syntax errors before they cause a batch job to fail.
• Keys and values are lowercase. PDF Checker expects lowercase JSON keys and values throughout.
• Back up your custom profiles in a separate directory so a local file mishap doesn't cost you hours of tuning work.

JSON Profiles in PDF Optimizer

PDF Optimizer's profile format follows the same philosophy but drives fixes instead of checks. It applies operations in a defined sequence:

1. Flatten transparencies — resolves rendering issues with drop shadows, soft masks, and blended objects in print workflows and older viewers.
2. Color conversion — converts images and objects to the target color space for the intended output medium.
3. Content optimization — image downsampling, recompression, font subsetting, and object removal.
4. PDF/A or PDF/X conversion — the final step for archival or print-compliance output, so you don't need a separate tool for compliance conversion.

Profiles are granular down to the content-type level: you can specify different downsampling resolutions and compression algorithms for color, grayscale, and monochrome images independently, or strip specific object types while preserving others.

PDF Optimizer ships with five predefined profiles covering the most common scenarios:

To run one, pass it with the -p flag alongside your input and output paths:

pdfoptimizer -i input.pdf -p compressionMedium.json -o output.pdf

Point the -i flag at a directory instead of a single file, and PDF Optimizer will apply the same profile across every PDF inside it — no separate scripting required for straightforward batch runs.

Putting Them Together: Check → Fix → Verify

Because both tools are JSON-driven and both support directory-level batch processing, they chain naturally into a single pipeline:

1. Run PDF Checker first. Scan the incoming document set and generate a report. For automated pipelines, generate that report as JSON rather than plain text — pass --json-output (or -s) and PDF Checker produces a machine-readable result you can parse programmatically instead of eyeballing a log.
2. Branch on the result. Documents with severe structural issues may not convert cleanly. Route those to a manual review queue instead of letting them fail silently inside your optimization pass. PDF Checker's report even includes a canBeOptimized tag and notes on how a document could specifically be improved with PDF Optimizer, so you can route intelligently rather than reprocessing everything the same way.
3. Run PDF Optimizer on what's left. Apply the appropriate predefined or custom profile — compression, print-readiness, or PDF/A conversion — to the documents PDF Checker cleared.
4. Verify with PDF Checker again. This "before and after" pattern is a common use case: run PDF Checker on the original document to generate a baseline record, process the file with PDF Optimizer, then run PDF Checker again on the output to confirm the targeted issue — for example, stripped JavaScript — no longer appears. This gives you an auditable record that a fix was actually applied, not just attempted.

This kind of workflow is easy to script: a JSON profile per stage, JSON output at each checkpoint, and ordinary logic (in whatever language you're already using — JavaScript, Python, a CI/CD job runner) to move documents between stages based on what the reports say.

Where This Fits in a Larger Pipeline

Both tools are built for server-side and unattended use, not just interactive, one-file-at-a-time runs:

• CI/CD integration: because both are command-line tools with file and directory inputs, they drop cleanly into build pipelines or scheduled jobs.
• Aggregated reporting: JSON output from both tools can be collected per document and rolled up into a database, giving you fleet-wide visibility into document health and optimization outcomes rather than a pile of individual log files.
• Security and compliance sweeps: the check-fix-verify pattern above is equally useful for confirming that sensitive content — embedded scripts, metadata, disallowed object types — has actually been removed, not just assumed to be gone.

Getting Started

Both tools are available as a free trial from datalogics.com, no credit card required. The PDF Optimizer trial includes the full tool, all five predefined profiles, PDF Checker itself, and complete documentation covering every JSON setting and command-line option. PDF Checker is free for internal use on its own.

A sensible first pass:

1. Run PDF Checker with everything.json against a representative sample of your document set and review the JSON or text report.
2. Route anything with severe structural problems to manual review.
3. Run PDF Optimizer's compressionMedium.json (or whichever predefined profile matches your goal) against the rest.
4. Re-check the output with PDF Checker to confirm the fixes landed.
5. Tune your JSON profiles based on what you see, then scale up to your full batch.

Datalogics technical support is available to all licensed customers for help with profile configuration or pipeline architecture questions.

FAQ

What's the difference between PDF Checker and PDF Optimizer? PDF Checker only diagnoses — it inspects PDFs and reports on structural errors, unembedded fonts, invalid color spaces, and similar issues without modifying the file. PDF Optimizer acts on those issues — it compresses, converts, and restructures PDFs to fix problems and reduce file size.

Do I need both tools? They're designed to be used together, and PDF Checker is included free with every PDF Optimizer purchase. Running PDF Checker before PDF Optimizer in a production pipeline is recommended so problem documents can be routed for review instead of failing mid-batch.

What is a JSON profile? It's a plain-text configuration file that defines exactly which checks (PDF Checker) or operations (PDF Optimizer) to apply, and with what settings. All settings are optional and off by default in both tools, so a profile gives you precise, repeatable control over what happens to your documents.

What predefined profiles are available? PDF Checker includes everything.json, which enables every check. PDF Optimizer includes compressionMedium.json, compressionHigh.json, PDFA-1b.json, PDFA-3u.json, and printing.json.

Can I get machine-readable output for automation? Yes. Both tools can produce JSON output instead of plain text, which is designed for scriptable workflows — driving conditional logic, aggregating results into a database, or triggering downstream processing based on what was found or fixed.

Try PDF Checker and PDF Optimizer for free and take control over how your PDFs are validated and processed.