Understanding PDF Checker Parameters and Optimizations

More than 25 years after its introduction, the PDF format still dominates how the world exchanges documents — an estimated 2.5 trillion PDF files are produced every year. But that ubiquity creates a quiet problem: PDFs are generated by a huge range of software, some of it decades old, so it's often hard to know what's actually stored inside any given file. Does it have unembedded fonts that will break someone else's rendering? Is it secretly a scanned image with no real text in it? Could it be made smaller without losing quality?

That's the problem PDF Checker solves. It's a free, scriptable command-line tool for 64-bit Windows and Linux that scans one or many PDF documents and reports back exactly what's inside — from structural issues and compliance claims to fonts, images, and metadata. Once you know what a document contains, you can pair PDF Checker with Datalogics' PDF Optimizer to actually fix what it finds: shrinking files, flattening transparency, removing clutter, or repairing damage.

Below, we walk through how PDF Checker works and what each of its parameters actually tells you.

How PDF Checker Works

PDF Checker runs from the command line, either one document at a time or as part of an automated batch process. Every run needs two things: the PDF file to inspect, and a JSON “profile” file that tells PDF Checker which checks to run and how to report them.

A basic command looks like this:

pdfchecker --input test.pdf --profile everything.json

Datalogics ships a default profile, everything.json, with every check turned on — a good starting point to copy and customize. Results can print to the console, or export to a human-readable text file, a machine-readable JSON file, or both, using the --output and --json-output flags. You can also pass a --password for protected files.

Each entry in the profile controls three things: whether the check runs at all (check), whether a match gets flagged as an Error or just Information in the report (report-as-error), and whether finding it should stop all further processing of that document (abort-remaining-checks) — useful in a batch job where you'd rather move on to the next file than keep analyzing one that's already disqualified.

General Parameters

These checks describe the fundamental nature of the document — whether it can even be opened, how it's secured, and what standards it claims to follow.

•     Unable to Open: the file isn't a valid PDF, or it's corrupted beyond repair.

•     Password Protected: the file needs a password, which can be supplied as a command-line argument.

•     Contains Owner Password: an owner password is set, restricting printing, copying, or editing while still allowing the document to be viewed.

•     XFA Type vs. AcroForms Type: identifies which forms technology the document uses. XFA is Adobe's proprietary, XML-based forms architecture; AcroForms is the far more broadly compatible standard, supported by nearly every PDF application.

•     PDF Version 2.0: flags documents built to the PDF 2.0 specification, published by ISO in 2017.

•     Contains Signature: checks for one or more digital signatures, which can be verified by a Certifying Authority and used to make the document legally binding.

•     PDF/A Conformance: PDF/A is the archival standard meant to keep documents readable decades from now. PDF Checker doesn't just note that a file claims PDF/A compliance — it verifies whether the claim is actually true, and identifies which variant is involved:

◦    PDF/A-1b — basic visual conformance.

◦    PDF/A-2b/2u — adds support for OpenType fonts, layers, and PDF/A-compliant attachments; the “u” variant also requires Unicode text mapping.

◦    PDF/A-3b/3u — like PDF/A-2, but allows embedding any file type, PDF/A-compliant or not.

•     PDF/X, PDF/E, PDF/VT, and PDF/UA: these cover other specialized standards — PDF/X for print and graphics exchange, PDF/E for engineering documents, PDF/VT for variable-data transactional printing, and PDF/UA for accessibility. PDF Checker can confirm whether a document claims each standard, though (unlike PDF/A) it doesn't verify the claim itself.

•     Born Digital vs. Image Only: distinguishes a document authored directly as a PDF (with real, searchable text) from one that's really just a stack of scanned page images. The two look identical to a reader, but only the scanned kind is a good candidate for OCR — running OCR on a born-digital file with no images gains you nothing.

•     Damaged: the file was corrupted and PDF Checker had to attempt an internal repair just to open it. If the repair succeeds, PDF Checker continues as far as it can and reports which checks completed; if it fails, the document is simply marked damaged and processing stops. (PDF Checker never saves the repaired version — that's a job for other Datalogics tools.)

•     Tagged PDF: checks for structural tags describing headings, paragraphs, and other content — the foundation that lets screen readers and other assistive tools interpret a document correctly.

Cleanup and Optimization Parameters

A PDF stores its text, images, and objects as compressed data streams. This check flags streams that are either uncompressed or using an inefficient, older compression method (like ASCII, Run Length, or LZW) — low-hanging fruit for PDF Optimizer to shrink.

Font Parameters

Fonts are one of the most common sources of PDF headaches, so PDF Checker looks at them from several angles:

•     Non-Extractable Text: flags fonts that prevent text from being pulled out of the document normally — which also means readers can't search within it.

•     Embedded vs. Not Embedded: best practice is to embed every font a PDF uses, so a viewer never has to hunt for (or substitute) a font from the local machine. PDF Checker reports fonts that aren't embedded — including the 14 “Base 14” fonts historically assumed to be present everywhere — as well as fonts that are fully embedded. Note: PDF Optimizer can subset embedded fonts down to just the characters actually used, shrinking the file, though this trades away easy future editing.

•     Font Descriptor Completeness: a font descriptor stores metrics like the font's name, italic angle, and ascent/descent. PDF Checker flags missing required fields, and separately checks for a commonly overlooked one, CapHeight — the height of capital letters above the baseline — which is required for any font using Latin characters.

Object and User Data Parameters

This group covers interactive and auxiliary content that can bloat a file or affect compatibility:

•     JavaScript Actions: flags embedded scripts, commonly used for things like submit buttons or auto-print commands. PDF Optimizer can strip these to shrink the file and improve compatibility.

•     Thumbnails: page-preview images shown in a viewer's side panel — removable to save space.

•     Annotations: covers notes, highlights, and comments generally, plus more specific cases: annotations hidden from view, annotations hidden from printing, and annotations missing a defined “normal appearance,” which can render inconsistently across viewers.

•     Optional Content (Layers): graphics or annotations that can be toggled on or off in Acrobat's Layers panel.

•     Transparency: objects stacked with partial opacity, blending visually with what's behind them. PDF Optimizer can “flatten” transparency — baking the blended result into a static image — to improve compatibility and speed up rendering.

•     Private Data: extra data some applications (like Adobe Illustrator) embed for their own future editing use. Removable to save space, at the cost of that app's ability to re-edit the file later.

•     Metadata: author, creation date, software used, and similar document properties — can be stripped to reduce file size.

•     Embedded Files: other files attached inside the PDF, from spreadsheets to other PDFs, which can add significant size.

Image Parameters

Images are usually the biggest contributor to file size, so PDF Checker evaluates color, grayscale, and monochrome images separately, each against its own resolution thresholds:

•     Resolution Too Low / Too High: flags images below or above a target DPI range. Defaults are 150–600 DPI for color and grayscale images, and 200–1200 DPI for monochrome. Low-resolution images may look poor; needlessly high-resolution ones just waste space.

•     Compression Format: identifies color and grayscale images using JPEG2000 compression, and monochrome images using JBIG2 (a compression format built specifically for black-and-white content).

•     Image Depth: flags 16-bit-per-channel color images — higher quality than the standard 8-bit, but substantially larger.

•     Alternate Images: some PDFs embed multiple versions of the same image (say, low-res for screen and high-res for print). This practice is rare today and can bloat files significantly when present.

Reading the Results

PDF Checker's report is organized by category — General, Userdata, Fonts, Cleanup, Images — and every match is labeled either an Error or Information, based on how you configured the profile. A summary block at the top (CHECKER_SUMMARY) lists every issue found, whether the file can be optimized, and its size in bytes, so a batch script can quickly triage which documents are worth running through PDF Optimizer at all — there's little point optimizing a 10 KB file.

If a document trips a check with abort-remaining-checks turned on, PDF Checker stops analyzing it right there and reports which checks did and didn't complete — saving processing time across a large batch. Two conditions always trigger this behavior regardless of that setting: a file that can't be opened, and a password-protected file opened without a password.

Because PDF Checker's threads run checks in parallel, the exact point where processing stops can vary slightly between runs of the same document — expected behavior, not a bug.

Getting Started

PDF Checker ships with a free trial of PDF Optimizer, so you can go from diagnosis to fix without switching tools. Check out the full command syntax, JSON profile structure, and error codes in our Developer Resources. Ready to see what's really inside your PDFs? Start a free trial today.