PDF/UA
PDF/UA (ISO 14289-1) is the PDF a screen reader can read: a tagged PDF that says what each thing on a page is, a heading, a paragraph, a table and its header cells, a list, a link, a picture and what it shows, and in which order to read them, and marks the rest, such as a header, a footer, a rule or a background, as decoration to skip. Accessibility law, such as the European Accessibility Act, now reaches the statements, invoices and tickets a system generates. Lpdf writes PDF/UA-1 when the document asks for it in its output, and the tags come from the document’s own elements: a table is tagged as a table, a list as a list.
<lpdf version="1"> <assets> <font name="body" src="fonts/Radley-Regular.ttf"/> </assets> <document font="body"> <meta title="Invoice 1234" lang="en-US"/> <output pdfua="1"/> <section> <layout margin="48pt"> <text role="h1" font-size="24pt">Invoice 1234</text> <text>Thank you for your order. The items and the amounts are below.</text> <text role="h2" font-size="16pt">Items</text> <table cols="3fr 1fr"> <thead> <td><text>Item</text></td> <td><text>Amount</text></td> </thead> <tr> <td><text>Consulting</text></td> <td><text>1,200.00</text></td> </tr> </table> </layout> </section> </document></lpdf>L.document({ font: 'body', assets: { fonts: [{ name: 'body', src: 'fonts/Radley-Regular.ttf' }] }, meta: { title: 'Invoice 1234', lang: 'en-US' }, output: { pdfua: '1' } }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.text({ role: 'h1', fontSize: '24pt' }, ['Invoice 1234']), L.text(NoAttr, ['Thank you for your order. The items and the amounts are below.']), L.text({ role: 'h2', fontSize: '16pt' }, ['Items']), L.table({ cols: '3fr 1fr' }, [ L.thead(NoAttr, [ L.td(NoAttr, [ L.text(NoAttr, ['Item']), ]), L.td(NoAttr, [ L.text(NoAttr, ['Amount']), ]), ]), L.tr(NoAttr, [ L.td(NoAttr, [ L.text(NoAttr, ['Consulting']), ]), L.td(NoAttr, [ L.text(NoAttr, ['1,200.00']), ]), ]), ]), ]), ]),])L.document(DocumentAttr(font='body', assets=DocumentAssets(fonts=[FontAttr(name='body', src='fonts/Radley-Regular.ttf')]), meta=DocumentMeta(title='Invoice 1234', lang='en-US'), output=DocumentOutput(pdfua='1')), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.text(TextAttr(role='h1', font_size='24pt'), ['Invoice 1234']), L.text(NoAttr, ['Thank you for your order. The items and the amounts are below.']), L.text(TextAttr(role='h2', font_size='16pt'), ['Items']), L.table(TableAttr(cols='3fr 1fr'), [ L.thead(NoAttr, [ L.td(NoAttr, [ L.text(NoAttr, ['Item']) ]), L.td(NoAttr, [ L.text(NoAttr, ['Amount']) ]) ]), L.tr(NoAttr, [ L.td(NoAttr, [ L.text(NoAttr, ['Consulting']) ]), L.td(NoAttr, [ L.text(NoAttr, ['1,200.00']) ]) ]) ]) ]) ])])L.document(new DocumentAttr().font("body").assets(new DocumentAssets().fonts(List.of(new FontAttr().name("body").src("fonts/Radley-Regular.ttf")))).meta(new DocumentMeta().title("Invoice 1234").lang("en-US")).output(new DocumentOutput().pdfua("1")), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.text(new TextAttr().role("h1").fontSize("24pt"), List.of("Invoice 1234")), L.text(NoAttr, List.of("Thank you for your order. The items and the amounts are below.")), L.text(new TextAttr().role("h2").fontSize("16pt"), List.of("Items")), L.table(new TableAttr().cols("3fr 1fr"), List.of( L.thead(NoAttr, List.of( L.td(NoAttr, List.of( L.text(NoAttr, List.of("Item")) )), L.td(NoAttr, List.of( L.text(NoAttr, List.of("Amount")) )) )), L.tr(NoAttr, List.of( L.td(NoAttr, List.of( L.text(NoAttr, List.of("Consulting")) )), L.td(NoAttr, List.of( L.text(NoAttr, List.of("1,200.00")) )) )) )) )) ))))L.Document(new() { Font = "body", Assets = new DocumentAssets(Fonts: [new FontAttr { Name = "body", Src = "fonts/Radley-Regular.ttf" }]), Meta = new() { Title = "Invoice 1234", Lang = "en-US" }, Output = new() { PdfUa = "1" } }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Text(new() { Role = "h1", FontSize = "24pt" }, ["Invoice 1234"]), L.Text(NoAttr, ["Thank you for your order. The items and the amounts are below."]), L.Text(new() { Role = "h2", FontSize = "16pt" }, ["Items"]), L.Table(new() { Cols = "3fr 1fr" }, [ L.Thead(NoAttr, [ L.Td(NoAttr, [ L.Text(NoAttr, ["Item"]), ]), L.Td(NoAttr, [ L.Text(NoAttr, ["Amount"]), ]), ]), L.Tr(NoAttr, [ L.Td(NoAttr, [ L.Text(NoAttr, ["Consulting"]), ]), L.Td(NoAttr, [ L.Text(NoAttr, ["1,200.00"]), ]), ]), ]), ]), ]),])L::document(new DocumentAttr(font: 'body', assets: new DocumentAssets(fonts: [new FontAttr(name: 'body', src: 'fonts/Radley-Regular.ttf')]), meta: new DocumentMeta(title: 'Invoice 1234', lang: 'en-US'), output: new DocumentOutput(pdfua: '1')), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::text(new TextAttr(role: 'h1', fontSize: '24pt'), ['Invoice 1234']), L::text(NoAttr, ['Thank you for your order. The items and the amounts are below.']), L::text(new TextAttr(role: 'h2', fontSize: '16pt'), ['Items']), L::table(new TableAttr(cols: '3fr 1fr'), [ L::thead(NoAttr, [ L::td(NoAttr, [ L::text(NoAttr, ['Item']), ]), L::td(NoAttr, [ L::text(NoAttr, ['Amount']), ]), ]), L::tr(NoAttr, [ L::td(NoAttr, [ L::text(NoAttr, ['Consulting']), ]), L::td(NoAttr, [ L::text(NoAttr, ['1,200.00']), ]), ]), ]), ]), ]),])The attributes
Section titled “The attributes”| Element | Attribute | Type | Description |
|---|---|---|---|
output |
pdfua |
1 |
Writes the PDF as PDF/UA-1, a tagged PDF. Without it, or a pdfa of level a, which tags the file too, nothing is tagged, and the attributes below change nothing |
meta |
lang |
language tag | The language of the text, such as en, en-US or de-CH, which a screen reader reads it in. Required with pdfua |
text |
role |
h1 … h6 |
Makes the text a heading. A text without it is a paragraph |
img, barcode |
alt |
string | What the image shows, or what the barcode is for; alt="" marks it as decoration. Required with pdfua on every image and barcode of the layout but a header’s or a footer’s, which are decoration |
layer |
alt |
string | Makes the layer one figure with that description. Without it a layer is decoration |
pdfua combines with pdfa: <output pdfa="2u" pdfua="1"/> writes an accessible file for the archive, and <output pdfa="2a" pdfua="1"/> one that is PDF/A level a too, the level for tagged files. Level a alone tags the file the same way, without the checks of PDF/UA. pdfua combines with pdfx too, for a print file a screen reader reads; a PDF/X file has no links, so its link text is read as text. What combines with what has every pair, and what each kind of file holds.
Headings
Section titled “Headings”A heading is a text with a role, h1 to h6. A screen reader lists the headings of a document and moves between them, so they say how it is built: the first is an h1, and going down they skip no level, from h1 to h2, never from h1 to h3. Going back up skips as many levels as it needs. The role changes nothing a page shows: set the size and the weight as on any text.
<text role="h1" font-size="24pt">Annual report</text><text role="h2" font-size="16pt">Revenue</text><text>Revenue grew in every quarter.</text>A Markdown heading is tagged with its level.
Images, barcodes and layers
Section titled “Images, barcodes and layers”An image says what it shows with alt, as in HTML, and alt="" marks it as decoration, which a screen reader skips. A barcode says what it is for: the data it encodes means nothing read aloud.
<img name="logo" width="80pt" alt="Acme Corp"/><barcode type="qr" data="https://pay.example/0042" width="72pt" alt="QR code to pay this invoice"/>A layer is decoration unless it says otherwise, as a header is: what a layer usually holds, a watermark, a running title, a logo’s letters, is on every page, and a screen reader would read it on each. A layer that shows something, such as a map with its city names, takes an alt and is read as one figure with that description, at its place in the document: a layer written before the layout is read before it, one after it after it. Its text-at are not read on their own.
<layer alt="A map of the two regions: North above South"> <circle x="470pt" y="690pt" r="22pt" fill="#cfe0fb"/> <text-at x="455pt" y="684pt">North</text-at></layer>L.layer({ alt: 'A map of the two regions: North above South' }, [ L.circle({ x: '470pt', y: '690pt', r: '22pt', fill: '#cfe0fb' }), L.textAt({ x: '455pt', y: '684pt' }, ['North']),])L.layer(LayerAttr(alt='A map of the two regions: North above South'), [ L.circle(CircleAttr(x='470pt', y='690pt', r='22pt', fill='#cfe0fb')), L.text_at(TextAtAttr(x='455pt', y='684pt'), ['North'])])L.layer(new LayerAttr().alt("A map of the two regions: North above South"), List.of( L.circle(new CircleAttr().x("470pt").y("690pt").r("22pt").fill("#cfe0fb")), L.textAt(new TextAtAttr().x("455pt").y("684pt"), List.of("North"))))L.Layer(new() { Alt = "A map of the two regions: North above South" }, [ L.Circle(new() { X = "470pt", Y = "690pt", R = "22pt", Fill = "#cfe0fb" }), L.TextAt(new() { X = "455pt", Y = "684pt" }, ["North"]),])L::layer(new LayerAttr(alt: 'A map of the two regions: North above South'), [ L::circle(new CircleAttr(x: '470pt', y: '690pt', r: '22pt', fill: '#cfe0fb')), L::textAt(new TextAtAttr(x: '455pt', y: '684pt'), ['North']),])What is tagged
Section titled “What is tagged”| What the document has | What a screen reader gets |
|---|---|
text |
A paragraph, or a heading with role. A text over several lines or pages is one |
table |
A table: the cells of thead are the headers of their columns, and the cells that span say how far |
list |
A list with its items. A number is an item’s label; a bullet or a checkbox is decoration |
link, and a span with href |
A link, described by its words |
fn |
A note at the foot of the page, with its number |
A toc section |
A table of contents with its entries |
markdown |
Headings with their level, paragraphs, lists, tables, and images with their alt text |
img, barcode, and a layer with alt |
A figure with its description |
A region (a header or a footer), a layer without alt, a divider, a shape, backgrounds, borders, and an image or a barcode with alt="" |
Decoration, which a reader skips |
| The header row of a table, repeated on the next page | Decoration: it is read once |
Print and screen content (ocg) |
Read as any other: a PDF/UA file shows everything, so a reader reads all of it |
A table’s header cells are those of its thead. A header in the first column of each row is not marked as one.
The date
Section titled “The date”A PDF/UA file carries the date it was made, as a PDF/A file does, so the render gives it as createdOn: an ISO 8601 date, or date and time.
A document built in code asks for PDF/UA in its output and gives its language in its meta: output: { pdfua: '1' } and meta: { lang: 'en-US' } in JavaScript, DocumentOutput and DocumentMeta in the other SDKs, where C# names it PdfUa. alt and role are on the attributes of the image, barcode, layer and text.
Errors
Section titled “Errors”Lpdf writes what PDF/UA needs and repairs nothing of the document’s own. Each of these stops the render with an error that says what to change:
- no
titleonmeta: a reader shows it in place of the file name - no
langonmeta, or one that is not a language tag - an
imgor abarcodeof the layout withoutalt, but in a header or a footer: the error names it - a first heading that is not an
h1, or a heading that skips a level going down - text in a built-in font, such as the default Helvetica, which is not embedded: declare a font in
assetsand set it withfonton the document or the text. The error names the text - a font declared in
assetswhose file was not loaded, and a font whose license forbids embedding it - a character the font has no glyph for, which a reader would draw as an empty box
- the digits of a barcode, drawn in Helvetica: set
hrt="false"and write the digits as text if they are needed - a form field, whose text is drawn in Helvetica
- an encrypted file whose
allowleaves outaccessibility: a screen reader must be allowed to read it - a render without
createdOn, or with one that is not a date
Checking a file
Section titled “Checking a file”A validator checks what a machine can: Lpdf’s own tests check a document with each thing that is tagged with veraPDF, the PDF Association’s reference validator, against its PDF/UA-1 profile on every change. To check a file of yours, run veraPDF on it. What only a person can judge, whether an alt text says what matters and whether the reading order makes sense, is checked by reading the file with a screen reader, such as VoiceOver on a Mac or NVDA on Windows.