Jacob Collins Jacob is the JPedal Product Manager and specialises in PDF creation and manipulation. He also develops Salesforce backend systems and contributes to marketing and support. Outside of work, he’s a 1900‑rated chess player, guitarist, and French learner.

Fix PDF files with the Arlington Model PDF Validator

Updated: 4 min read

JPedal Java PDF library logo

The November release of JPedal (2026.11) adds a ‘fix mode’ to our Arlington Model PDF Validator. Until now the validator could only tell you what was wrong with a PDF file. In fix mode it can repair some of those issues itself and write out a fixed copy of the file.

What is the Arlington PDF Model?

The Arlington PDF Model is the PDF Association’s machine-readable definition of the objects in the PDF specification. It covers which keys each object can have, what types their values must be, which values are permitted, and which objects must be indirect.

JPedal’s validator checks a file against that model and reports each issue with a severity, the path to the offending object, and the rule it breaks. We added it to JPedal in August, and covered it in our post on PDF/A compliance in Java.

What fix mode fixes

Fix mode only makes a change when the model leaves no doubt about the result: a default value to add, an optional key that can be dropped, or an object that must be indirect. It will:

  • Add a missing required key or array element if the model gives it a default value. For example, an associated file specification with no AFRelationship gets the default value /Unspecified.
  • Remove an optional key with an invalid value where the value is the wrong type, is not one of the permitted values, or fails its special case. For example, a catalog with a PageLayout of /AnUndefinedOption has the key removed, so a viewer falls back to the default layout.
  • Move a direct object to a new indirect object where the model requires it to be indirect. A font descriptor written inline inside its font dictionary is one example.

What fix mode does not fix

Everything else is still reported as an issue in the file. The validator does not guess at a value the model does not give it, so a required key with no default, or a Widths array of the wrong length, is left as it is. If any of these remaining issues is an error, the fixed file will not be written (see below).

Encrypted files cannot be fixed. Attempting to fix one will throw an IOException.

How the fixed file is checked

Once the fixes have been made, the fixed file is validated again. It is only written out if no errors remain. Warnings and info messages do not stop it being written. The issues you get back are the ones in the fixed file, not the original. The fixed file is written out even if nothing needed fixing.

Using fix mode from the command line

To use the command line you will need a copy of the model in TSV format. Clone or download the Arlington PDF Model repository and pass the location of its tsv/latest directory to --tsv.

Pass --fix with a directory to write the fixed files to. Each fixed file is given the same name as its input file, and the input file is never overwritten.

java -cp jpedal.jar org.jpedal.arlington.validate.PdfArlingtonValidator --tsv <path-to-arlington-tsv-dir> [--level LEVEL] --fix <output-dir> file1.pdf [file2.pdf ...]

Each fix is printed as [FIXED] path-in-pdf (arlington-object-definition): fix-message, followed by any issues which remain in the fixed file.

[FIXED] Trailer/Root/PageLayout (Catalog): Removed optional key 'PageLayout' with an invalid value (Value of 'PageLayout' (/AnUndefinedOption) is not one of the permitted values [SinglePage, OneColumn, TwoColumnLeft, TwoColumnRight, TwoPageLeft, TwoPageRight])
[FIXED] Trailer/Root/Pages/Kids[0]/Resources/Font/F2/FontDescriptor (FontCIDType0): Moved direct object to indirect object 12 (Value must be an indirect reference (fn:MustBeIndirect) but is a direct object)
[FIXED] Trailer/Root/AF[0] (AFFileSpecification): Added default value /Unspecified (Required key/element 'AFRelationship' does not exist)
3 fix(es) applied, fixed file written to "fixed/file1.pdf"

Using fix mode in Java

The model comes bundled with the JPedal jar, so there is nothing extra to download. Load the model, then call PdfArlingtonValidator.fixFile() with the location to write the fixed file to, which must not be the input file. Files may be loaded from a File, byte[], or InputStream.

final Map<String, ArlingtonObject> model = ArlingtonModelLoader.loadClasspath("arlington-pdf-model");

final PdfArlingtonValidator.FixResult result = PdfArlingtonValidator.fixFile(new File("inputFile.pdf"), model, new File("outputFile.pdf"));

for (final AppliedFix fix : result.fixes()) {
    // Iterate over the fixes which were made
}
for (final ValidationIssue issue : result.issues()) {
    // Iterate over the issues which remain in the fixed file
}
if (!result.written()) {
    // Errors remain, so the fixed file was not written
}

Always check written() before using the output file. If it is false, no file was written and the issues list tells you what is still wrong.

Fixing large files

Fixed files are held in memory while they are validated again. If a file is larger than the memory cache threshold, it is written to an encrypted temporary file in the output directory instead. The default threshold is 58MB, and you can change it:

PdfArlingtonValidator.setMemoryCacheThreshold(10_000_000); // 10MB

Download JPedal to get started

Download a JPedal jar from our website to start validating and fixing PDF files.

Resources

The Arlington validation tutorial covers validation and fix mode from both the Java API and the command line.

We can help you better understand the PDF format as developers who have been working with the format for more than 2 decades!