Accessibility and structure / PDF/UA-1
PDF/UA-1 compliance for a generated PDF
ISO 14289-1: the standard that says a PDF is usable by assistive technology, which in practice means it carries a complete and correct structure tree.
Where this API stands
This API does not produce this standard, and there is no option that would. What follows is what the requirement actually is and where a rendered document stands against it. This API does not produce PDF/UA-1 and has no option that moves a file towards it. There is no way to ask it for /MarkInfo, for a /StructTreeRoot, for /Lang, or for /ViewerPreferences /DisplayDocTitle, and the one conformance option it does have, `pdf_a`, targets PDF/A-1b and writes only a pdfaid identification packet. What does carry forward is your markup: real headings, real table cells, real list elements and a real `alt` on every image are the raw material any later tagging pass has to work from. A document built out of styled divs cannot be made conformant by any tool at any price, because the information a tagger would need was never written down.
What the standard requires
The requirements as a checker enforces them, rather than as a procurement document paraphrases them. A file satisfies all of these or it satisfies none of them.
- The catalogue carries /MarkInfo with /Marked true, which is the file declaring that its content is marked up rather than merely drawn.
- A /StructTreeRoot exists and every piece of real content is reachable from it, in the order a person would read it.
- A natural language is declared for the document in /Lang, and again on any passage in a different language.
- Every image carries alternative text, or is explicitly marked as an artifact, and there is no third option.
- /ViewerPreferences carries /DisplayDocTitle true, so a reader shows the document title rather than the filename in the window bar.
- An XMP packet declares pdfuaid:part 1, which is how a validator knows the file is claiming conformance at all.
Who asks for this
Public sector procurement, most often. Accessibility requirements for public bodies in the EU and in the United States both point at WCAG 2.1 level AA, and PDF/UA is the recognised way of satisfying that for a PDF rather than for a web page. Large enterprises increasingly ask for it in supplier onboarding because their own obligations flow down the contract. The awkward part is that the requirement usually arrives as one line in a questionnaire, months after the document pipeline was built.
What it looks like in a file
The concrete form of the thing being described, so you can recognise it in a document you have been handed rather than only in a specification.
% What a PDF/UA-1 file has in its catalogue that a plain one does not.
% Dumped with: mutool show file.pdf trailer/Root
<<
/Type /Catalog
/MarkInfo << /Marked true >>
/StructTreeRoot 42 0 R
/Lang (en-GB)
/ViewerPreferences << /DisplayDocTitle true >>
/Metadata 7 0 R % must declare pdfuaid:part 1
/Pages 3 0 R
>>What to do about it
Treat tagging as a step after rendering, and pick the tool before you commit to the pipeline. callas pdfToolbox and Adobe Acrobat Pro can both auto-tag and then let a person fix what auto-tagging got wrong, which is always something. axesPDF and CommonLook sell tools aimed specifically at PDF/UA remediation. Budget for the human pass: auto-tagging gets a simple report most of the way and gets a complex table nowhere. If the volume is high and the layout is fixed, the cheaper answer is often to generate the tagged file from the source data with a library that emits structure directly, and use the rendered PDF only for the human-facing preview.
How to check a file rather than assume
PAC 2024 is the free checker most people use, and it reports against the Matterhorn Protocol, which is the checkpoint list PDF/UA conformance is actually assessed against. veraPDF also has a PDF/UA profile. Both will tell you immediately whether there is a structure tree at all, which is the answer that matters before any of the finer checkpoints are worth reading.
The mistake people make here
Believing that a passing validator means an accessible document. PAC checks what can be checked mechanically: that a figure has alt text, not that the alt text describes the figure. A file can pass every automated checkpoint and still be useless to a screen reader user because the reading order is wrong or every image is described as "image". The automated pass is the floor, not the ceiling.
Frequently asked
Does this API produce PDF/UA-1?
Not produced by this API. This API does not produce PDF/UA-1 and has no option that moves a file towards it. There is no way to ask it for /MarkInfo, for a /StructTreeRoot, for /Lang, or for /ViewerPreferences /DisplayDocTitle, and the one conformance option it does have, `pdf_a`, targets PDF/A-1b and writes only a pdfaid identification packet. What does carry forward is your markup: real headings, real table cells, real list elements and a real `alt` on every image are the raw material any later tagging pass has to work from. A document built out of styled divs cannot be made conformant by any tool at any price, because the information a tagger would need was never written down.
Can I turn on the pdf_a option and be done?
No. The option writes an XMP packet declaring PDF/A-1b into the document catalogue, and the render response comes back carrying a warning that says in as many words that this is best-effort and that full conformance requires tagged structure and an embedded ICC profile. It is a claim written into the file, not a certificate earned by it, and a validator checks the claim against the bytes. Read the warning array in the response rather than taking the absence of an error as a pass.
Should I convert before rendering or after?
After, always. A conformance converter rewrites colour, embeds profiles, sets boxes and stamps metadata on a finished PDF. Trying to satisfy a conformance target from the source side means guessing at what the converter would have done, and the guesses that go wrong are expensive: flattening transparency you did not need to flatten changes what the page looks like.
Standards this one is confused with
The neighbours that matter are the ones people mistake for this, not the ones that sort next to it.
How to tell if a PDF is tagged
A tagged PDF carries a second, invisible copy of itself: a tree of headings, paragraphs, lists and cells that says what the content is, rather than where the ink goes.
The logical structure tree in a PDF
The tree of typed elements, Document at the root and paragraphs, lists, tables and figures below it, that describes what the document is made of.
PDF/A-1a: the tagging requirement that 1b does not have
Everything PDF/A-1b requires, plus a complete logical structure tree, a declared document language and a Unicode mapping for every glyph, so the file is readable by a machine and not only by an eye.
Reading order in an accessible PDF
The sequence a screen reader speaks the document in, which comes from the order of elements in the structure tree and not from where anything sits on the page.
Alt text on images in a PDF
A text description attached to a figure structure element, which is what a screen reader speaks in place of an image it cannot see.
Every standard, with what this API does about it
The full list, grouped by what the requirement is for, each marked with how far this API gets.
What this API actually does
One page per option and endpoint that exists, with nothing that does not.
Conformance is decided after a file exists. Render the document, then check it, then convert only what the checker actually flags.