What we check, and how we repair

This page is about the engine behind the tool: which checks run, what the repair changes in your file, and where it stops on purpose. For anyone who wants to know where a number in the report comes from.

Two things that are not the same

The tool runs a check and a repair, and the two are separate. The check looks at what is in the file and judges it. The repair changes the file. Your report runs the check twice: once on the document as it came in, and once on the document as it goes out. The difference between the two is what was fixed.

The check

The checks come from the Proper Access knowledge base, which describes for each scenario what is wrong, why a reader notices it and how you fix it. Each scenario has a number, and that number is in your report: T-PDF-1.1.1-01 is about WCAG success criterion 1.1.1, and the sequence number after it tells the cases within that criterion apart.

This tool knows 31 scenarios, and 31 of them run on every document. They are spread over 23 checks that each look at their own part of the file. The other 0 are further down, under "What does not run".

What the check looks at

The check reads the tag structure, the metadata and the text the way assistive technology finds them. It does not open your document as an image and does not judge what it says. Broadly, it looks at:

• The tag structure itself. Is there a structure tree, is the content in it, and is what falls outside it marked as an artifact.
• Headings. Heading tags without content, and text that looks like a heading but has no heading tag. The second one works on the font size compared to the body text.
• Images. A /Figure without /Alt or /ActualText, and alt text that a program seems to have filled in, such as "image 4" or "picture 12".
• Tables. Tables without header cells, and cells whose header is ambiguous.
• Lists. An /L without items, items without a body tag, and paragraphs that start with a bullet without being in a list.
• Reading order. The order in the tags compared to the order on the page.
• Title, language and the document settings. A title in the metadata, a language on the catalog, and DisplayDocTitle, which decides whether a reader sees the title or the file name in the title bar.
• Form fields. A document with fields where copying is turned off: anyone who has to move information from the document into the fields can then only retype it.
• Links and form fields. A link annotation that is not inside a /Link tag, a link without a usable name, and the tab order of a page with annotations.

Three levels

Every finding has one, and the level says what the tool knows, not how serious it is.

• Error. The tool has established that it is wrong.
• Check. There is a sign, and whether it is right is a judgement. Alt text that says "image 4" is usually not alt text; sometimes there really is an image with that caption.
• Advice. It is allowed, and it could be better. Bookmarks in a long document are the example.

The repair

The repair runs in four steps, in this order, followed by a check on how the pages look.

1. Add tags, if there are none. OpenDataLoader does this: an open source program that goes through the drawing instructions of each page and turns them into headings, paragraphs, lists and tables. It runs on our own server; your document does not leave it. If the document already has a tag structure, that structure stays as it is.
2. Remove tags that point to nothing. A tagger sometimes makes a table out of the grid lines of a chart. A grid of empty cells like that announces a table that is not there, which is worse than no table. The same goes for a heading tag around only a space or around nothing: it is removed from the structure, and whatever was on the page becomes an artifact. A heading with only a line or another drawing under it stays. These are the only parts of the repair that remove anything.
3. Mark header cells. A tagger makes every cell a /TD; it does not know which row is the header. This step reads the formatting from the drawing instructions and only changes a cell when the evidence is clear: a top row that is bold while the rows below are not, or a left cell that is bold while the rest of the row is not. If the code cannot find the font of a deciding cell, the table stays as it is. For a screen reader, a header on the wrong row is worse than no header: every cell is then announced with the wrong column, and nothing on the page shows it.
4. Set the metadata. The title, the language, DisplayDocTitle and MarkInfo, and for a tagged document the PDF/UA identifier. They are all in the document dictionary or in the metadata, not in the pages, so nothing you see changes.

The visual check

After every repair we render each page of the original and of the result, and compare them pixel by pixel. If they differ, your report says so. The repair should change the tags and not the page layout, so a difference is a reason to look. If you change a text colour yourself in the editor, the page is supposed to change, and then the tool does not report it as a difference.

What the repair does not make up

The tool cannot know a title that is not anywhere in the file. Anything taken from the text is marked that way in your report, with the reason, and a derived title holds back the delivery until a person has looked at it. The language is derived from common words, and only when there is enough to go on: below that threshold the field stays empty. A wrong language is worse than a missing one, because a screen reader then reads Dutch text with an English voice.

The tool never writes alt text. The person who made the document knows what is in an image.

What does not run

0 of the 31 scenarios are in the knowledge base but do not run in this tool yet. Your report says nothing about them, and that is not the same as "fine".

Where the tool stops

Most of what makes a document accessible is a judgement about the content. The tool does not touch that. It is not a shortcoming: it is the limit of what a program can know.

• Whether alt text is the right alt text. The tool sees that there is text, not whether that text describes the image.
• Whether a heading has the right level. Levels that go up in order say nothing about how your content is structured.
• Whether the reading order is right. The tool sees that the tag order differs from the order on the page. The author knows which of the two is right.
• Whether the title fits the document. A title that meets the rules can still be the wrong title.
• Colour and contrast. The check says nothing about this, because that requires rendering the page. The contrast screen in the editor does render it, and measures every colour combination against the requirement of 4.5 to 1.

What this is not

This is not a PDF/UA declaration and not a conformance statement. PDF/UA-1 is a different standard from WCAG, with its own requirements, and not all of them are about the reader. We check against what a visitor notices, and the numbers in your report refer to WCAG success criteria.

For a tagged document we do add the PDF/UA-1 identifier to the metadata. PAC and veraPDF report it when it is missing, and a reader does not notice it. It is no guarantee that your document meets PDF/UA.

It does not replace an audit either. An audit is the work of an auditor who reads your document, goes through it with a screen reader and gives a judgement on it. This tool takes over the part a machine can do, so there is time left for the rest.

Repair a document Terms