Accessible PDFs (PDF/UA) and PDF 2.0 — Alpha

Alpha

PDF/UA output is in alpha. The request fields and response headers below may still change, and every response that uses them says so with X-PDF-Standard-Stability: alpha. Tell us how it works for you through the dashboard's contact form.

Add pdf_standard to a conversion or template render and PodPDF makes a tagged, accessible PDF that conforms to:

`pdf_standard`	Standard	PDF version
`pdf/ua-1`	PDF/UA-1 (ISO 14289-1)	1.7
`pdf/ua-2`	PDF/UA-2 (ISO 14289-2:2024)	2.0

pdf/ua-1 is what most accessibility checkers and procurement rules ask for today. Choose pdf/ua-2 when you specifically need PDF 2.0.

Leave pdf_standard out and nothing changes: you get the same PDF as always.

Where it works

Endpoint	During the alpha
`POST /quickjob` with `input_type` `html` or `markdown`	✅
`POST /longjob` with `input_type` `html` or `markdown`	✅
`POST /templates/{template_id}/render`, visual and HTML templates	✅
`input_type: url`, images, bulk, mail merge, `/pdf/*`	Not yet: `400 INVALID_PARAMETER`

It costs the same as any other PDF.

Quick example

curl -X POST https://api.podpdf.com/quickjob \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_type": "html",
    "html": "<html lang=\"en\"><head><title>Invoice INV-1042</title></head><body><h1>Invoice</h1><p>Thank you.</p></body></html>",
    "pdf_standard": "pdf/ua-1"
  }' \
  -D headers.txt -o invoice.pdf

X-PDF-Standard: pdf/ua-1
X-PDF-Standard-Stability: alpha
X-PDF-Conformance: pass

Request fields

Field	Description
`pdf_standard`	`"pdf/ua-1"` or `"pdf/ua-2"`
`title`	Optional. The title PDF readers show. Defaults to the page's `<title>`, then its first heading
`lang`	Optional. The document language, such as `en`, `en-GB` or `de`. Defaults to the page's `<html lang>`, then `en`

title and lang only apply together with pdf_standard.

What PodPDF does, and what stays yours

PodPDF handles everything the file needs:

tags from your HTML's structure, with headings renumbered to start at H1 and never skip a level
document language, title, and XMP metadata identifying the standard
page headers, footers, borders and list bullets marked as decoration, so screen readers skip them
a description on every link
bookmarks from your headings
empty table cells kept, so table columns line up for screen readers
for pdf/ua-2: a PDF 2.0 file, with bookmarks and same-page links pointing at the right element

What depends on your content stays yours:

Do	Why
`alt="…"` on every meaningful `<img>`, `alt=""` on decorative ones	An image without alt text fails the check
`role="img"` and `aria-label="…"` on a meaningful inline `<svg>` (charts, diagrams)	Without them an SVG is treated as decoration
Real headings (`<h1>`–`<h6>`), not bold paragraphs	Screen readers navigate by them
`<th>` for header cells in data tables	Header cells give each value its meaning
Real lists (`<ul>`, `<ol>`) and paragraphs	Reading order and structure come from the markup
No links inside `headerTemplate` / `footerTemplate`	Page furniture is decoration, so a link there can't be tagged

Built-in starter templates pass both standards with their sample data. Images in visual templates use the alt text set on the image block, and barcodes and QR codes are described by their value.

Reading the result

Every pdf_standard render is checked with veraPDF, the open-source reference validator, and the PDF is always returned:

`X-PDF-Conformance`	Meaning
`pass`	veraPDF found no failures
`fail`	Something did not conform. `X-PDF-Conformance-Failed-Rules` lists up to ten rules, such as `7.1-3,7.18.5-2`
`unavailable`	The check could not run in time. The PDF was still made to the standard

With store: true, the JSON response carries the same result:

{
  "job_id": "9f0a4b78-2c0c-4d14-9b8b-123456789abc",
  "pages": 1,
  "download_url": "https://…",
  "pdf_standard": "pdf/ua-1",
  "pdf_standard_stability": "alpha",
  "conformance": {
    "status": "fail",
    "validator": "veraPDF 1.30.3",
    "failed_rules": [
      {
        "rule": "7.3-1",
        "specification": "ISO 14289-1:2014",
        "description": "Figure tags shall include an alternative representation or replacement text…",
        "failed_checks": 1
      }
    ]
  }
}

Long jobs record the result on the job: see pdf_standard and conformance in GET /jobs/{job_id}. The job.completed webhook carries it too.

Common failures and their fix:

Rule	Fix
`7.3-1` (UA-1), `8.2.5.28.2-1` (UA-2): a figure has no alternate text	Add `alt` to the image, or `aria-label` to the SVG
`7.18.5-1` (UA-1): a link is not tagged	Move the link out of the header or footer template

Limits of an automated check

veraPDF checks everything a machine can check. Some requirements need a person: whether alt text describes the image well, whether the reading order makes sense, whether colour alone carries meaning. For documents with legal accessibility obligations, review a sample with a screen reader or with PAC as well.

Where it works​

Quick example​

Request fields​

What PodPDF does, and what stays yours​

Reading the result​

Limits of an automated check​