Accessibility preflight

FreePDF includes a native, offline PDF/UA-1 preflight, with explicitly partial coverage. It inspects the original bytes without repairing or saving the PDF. It does not certify ADA, WCAG, Section 508 or complete PDF/UA compliance. There is deliberately no IsAdaCompliant property or overall Passed outcome.

using PdfSharp.UniversalAccessibility;

var report = PdfAccessibilityScanner.Scan("document.pdf");
foreach (var finding in report.Findings)
    Console.WriteLine($"{finding.RuleId}: {finding.Message} (page {finding.Page})");

// A completed scan can still contain failures and always requires review.
Console.WriteLine($"{report.Status}; coverage: {report.Coverage}");

The stream overload reads from the current position to EOF, leaves the stream open and restores its original position when seekable. Reports contain the SHA-256 of the inspected bytes, a versioned rule set, check outcomes, locations, guidance and the author-supplied structure order. Report text, including alternative text, is untrusted document content and can also contain confidential information.

Implemented checks

All IDs have the prefix FPDF-A11Y-. An individual Passed means only that the named check passed for its inspected occurrences. NotApplicable means no applicable occurrence was found. A failure takes precedence over other occurrences; the findings still record unassessed occurrences and ScanCompleted remains false if any implemented check could not finish. When a limit stops the scan, every check that had not inspected all its occurrences becomes NotChecked; failures already found stay Failed, and HasFailures reports them.

ID Scope
READ Readable without repair: a rebuilt or corrected cross-reference table, or a stream length recovered from endstream, makes it NotChecked; also bounded inspection and unreadable/password-protected inputs
LANG Presence of a nonempty catalog language
TITLE Nonempty XMP dc:title
UAID XMP pdfuaid:part=1; PDF/UA-2 is reported as unsupported
DISPLAYTITLE ViewerPreferences/DisplayDocTitle=true
MARKED / SUSPECTS Marked-content declaration and suspect-tagging flag
TREE Nonempty structure root, child types, parent references, cycles and duplicate elements
ROLE Standard PDF 1.7 structure roles and bounded custom role-map resolution
ALT Presence of Alt or ActualText for figures and formulas
NESTING Basic list/item/label/body and table/row/cell parent relationships
MCID IDs within each page or form, structure references, ParentTree entries and repeated use of a form with its own IDs
CONTENT Painting inside tags or artifacts and balanced marked-content scopes in pages and invoked forms
FONT Embedded font programs for visible text in pages and invoked forms, except in text rendering mode 3 (invisible)
TABS Structure tab order on annotated pages
ANNOT Structure object references for links/widgets
REVIEW Required human accessibility review

Starting with 7.13.0, the scanner follows each Do that draws a local Form XObject. A form can inherit the caller's tag or artifact, or contain its own tagged content. The scanner matches each form's IDs to its structure references and parent tree. A finding includes the page and resource path, for example /Resources/XObject/Outer/Resources/XObject/Inner. A resource name longer than 127 bytes is cut and ends with .... A location longer than 1,024 characters keeps its start and its end, joined by /....

The scanner looks up named property lists in the active resources. A legacy form that omits its resource dictionary uses the page resources. An unresolved property, a recursive form or a complex inline property that the scanner cannot interpret produces NotChecked. A definite failure elsewhere in the document still gives exit code 1.

PdfAccessibilityScanOptions sets the scan limits. MaxDecodedBytes covers metadata, page streams and each form invocation. MaxDepth bounds nested forms and XMP elements. MaxNodes covers the structure tree, role map and number tree. Equal consecutive saved graphics states share one entry, and more than 65,536 distinct saved states stop the scan. MaxDuration (default 2 minutes, null for no limit) ends a scan that takes longer; the failures found until then stay in the report. MaxDuration and the cancellation token also stop the reader while it opens the PDF. A limit produces Incomplete. Cancellation propagates to the caller. The metadata reader disables XML DTD processing.

The scanner reads content one operator at a time. If a stream cannot be parsed to its end, failures found before the error remain in the report, and the scan is Incomplete.

The checks are a starting point, not the complete Matterhorn/PDF/UA test set. They do not validate Unicode mappings, embedded glyph correctness, all heading/table semantics, widget accessible names, annotation appearance streams, optional content, all parent-tree rules, security permissions or PDF/UA-2. Language presence does not prove its correctness; alternative-text presence does not prove its usefulness. Use an independent validator such as veraPDF, document review and actual assistive-technology testing before making a conformance claim. The HTML structure listing is a review aid, not a screen-reader transcript.

The library's limits are not a security sandbox. Process untrusted files in an isolated worker with external time/memory limits. The regression tests scan six hostile inputs that each once needed between 1 and 5 GB; each must now finish within a 256 MiB .NET heap. That covers known cases, not every possible file. Opening a PDF keeps all its objects in memory, about 500 bytes each. A file within MaxFileBytes that packs millions of small objects into compressed object streams can therefore need several GB: 19 MiB with 3 million objects used 1.5 GB and opened in 6 s, well within the default MaxDuration. The corpus runner demonstrates per-file process isolation, timeouts and a .NET GC heap limit; its inputs are synthetic, and a GC heap limit is not a total process-memory limit.

Command line and reports

Start with a PDF and the .NET 10 SDK. From the repository root:

dotnet run --project src/tools/FreePDF.Accessibility -c Release -- document.pdf

The default text summary says whether it found problems, needs human review or could not finish. Findings explain the problem and the next step. A result of "Human review required" means the implemented checks found no failures; it does not mean the document has passed all accessibility requirements. For example, software can find a missing image description, but a person must decide whether an existing description explains the image correctly.

Build the .NET 10 CLI from source:

dotnet build src/tools/FreePDF.Accessibility/FreePDF.Accessibility.csproj -c Release
dotnet src/tools/FreePDF.Accessibility/bin/Release/net10.0/FreePDF.Accessibility.dll \
  document.pdf --format html --output audit.html

Formats: text (default), json, sarif (2.1.0) and script-free html. The text summary shows up to 20 findings, prioritizing failures and incomplete checks. It escapes terminal control characters from filenames and document text. Use HTML or JSON for all findings. HTML escapes document strings and loads no external resources. SARIF includes rule IDs, guidance, document hashes, page/path locations, review tasks and coverage metadata. JSON and HTML reports cut alternative text in the structure order after 1,000 characters and end it with ..., because many elements can share one long text. PdfAccessibilityStructureEntry.AlternativeText in the API keeps the whole text. Output paths must be new files: the CLI refuses to overwrite an existing report or PDF. Use --password-env NAME for an environment variable containing the password. --timeout SECONDS (1 to 3600, default 120) sets MaxDuration for the native scan. The password is never included in the report.

Exit Meaning
0 Explicit --policy automated satisfied; human review still required
1 At least one implemented check failed, also when the scan is incomplete
2 Human review required (default policy for otherwise successful scans)
3 Incomplete scan without a detected failure: unsupported content, a repaired file or limits
64 Invalid command/options or input/output error

A detected failure decides the exit code. In the report, status stays Incomplete when some content could not be checked, hasFailures says whether a check failed, and scanCompleted says whether every check finished. SARIF carries both values in the run properties. --policy automated never turns an incomplete scan into success.

The CLI is published on NuGet.org as the .NET tool io7.FreePDF.Accessibility.Tool (command freepdf-a11y) since 7.11.0. The scanner itself ships in the existing library assemblies, including the Core, GDI and WPF variants.

dotnet tool install --global io7.FreePDF.Accessibility.Tool
freepdf-a11y document.pdf --format html --output audit.html

To use a build from a source checkout instead, pack and install it into a new local directory (run from the repository root):

dotnet pack src/tools/FreePDF.Accessibility -c Release -o artifacts/a11y-package
dotnet tool install io7.FreePDF.Accessibility.Tool --tool-path artifacts/a11y-tool \
  --source artifacts/a11y-package
artifacts/a11y-tool/freepdf-a11y document.pdf
artifacts/a11y-tool/freepdf-a11y document.pdf --format html --output audit.html

Open audit.html in a browser. The PDF stays on your machine and is not modified. The report can include document content, so handle it with the same care as the PDF.

Validation and next coverage

FreePDF 7.12.0 adds an optional veraPDF adapter and a complete Matterhorn inventory. Use freepdf-a11y --requirements to inspect the inventory. Independent machine results remain separate from native findings and human review.

The regression suite includes positive, negative, cyclic, encrypted, malformed, resource-limit and original-byte-preservation cases. CLI contracts test exit policies, JSON/SARIF structure, HTML escaping and output overwrite protection. CI runs the installed CLI on nine synthetic files with veraPDF 1.30.3. The adapter tests record each validator's result, including the repeated-form difference.

Future releases can extend the versioned rules with Unicode/glyph validation, complete annotation/form/table rules, then generation preflight and reviewed remediation. Automatic repair, AI-written alternative text, PDF/UA-2 and organizational review sign-off are not part of this first implementation.

See the accessibility roadmap for the proposed path to complete automated coverage and a documented human review process.

References: Matterhorn Protocol, W3C PDF techniques, veraPDF validation scope.