PDF/UA-Konformität programmatisch prüfen mit veraPDF

Was veraPDF prüft, und was nicht

veraPDF ist ein Open-Source-Validator, der prüft, ob ein PDF die machine-verifizierbaren Anforderungen der ISO-Normen PDF/A (14289 für PDF/UA ist die Schwester-Norm) und PDF/UA erfüllt. Das Projekt wurde 2014 als Konsortium aus PDF Association, Open Preservation Foundation, Digital Preservation Coalition und anderen ins Leben gerufen. Die Validierungsregeln werden in maschinenlesbarer Form aus den ISO-Klauseln abgeleitet und sind im Validation-Profile-Repository öffentlich einsehbar.

Machine-verifizierbar ist hier der zentrale Begriff. Ein Validator kann prüfen, ob ein Tag-Baum existiert, ob jedes Bild ein /Alt -Attribut trägt, ob alle benannten Strukturtypen in einer Role-Map abgebildet sind. Er kann nicht prüfen, ob ein Alt-Text inhaltlich passt, ob die Lese-Reihenfolge sinnvoll ist oder ob eine Tabelle wirklich eine Tabelle sein sollte. Beide Klassen, die maschinelle und die menschliche, sind in der ISO-Norm gleichberechtigt; veraPDF deckt die maschinelle Klasse vollständig ab.

Profile: PDF/UA-1, PDF/UA-2 und PDF/A

veraPDF arbeitet mit Validation Profiles. Jedes Profil entspricht einer ISO-Norm-Variante. Die wichtigsten für Barrierefreiheits-Validierung sind:

Wer den Standard nicht kennt, fängt mit --flavour ua1 an. Erst bei expliziten PDF/UA-2-Ausgaben (etwa aus Typst oder aktuellen LaTeX-Tagging-Builds) wechselt man zum 2-Profil, und nur dann sind die strengeren ISO-14289-2-Klauseln aktiv.

CLI: Validierung in einer Zeile

Die Kommandozeilen-Verwendung ist der häufigste Einstieg. Nach der Installation (siehe veraPDF-Dokumentation; verfügbar als ZIP, Docker-Image und für Linux als .deb ) reicht ein Aufruf:

 # 1. Einfache PDF/UA-1-Validierung 
verapdf --flavour 
ua1 dokument.pdf # 2. Ausführlicher Bericht als XML, gut für Tools 
verapdf --flavour 
ua1 --format 
mrr dokument.pdf > bericht.xml # 3. Stapelverarbeitung: ganze Ordner prüfen 
verapdf --flavour 
ua1 --recurse./alle-pdfs/ > bericht.xml # 4. Mit JSON-Bericht (seit veraPDF 1.22) 
verapdf --flavour 
ua2 --format 
json dokument.pdf > bericht.json # 5. Exit-Code prüfen: 0 = konform, >0 = Befunde 
verapdf --flavour 
ua1 dokument.pdf echo 
 "Exit-Code: $?" 

Wichtig ist Punkt 5: veraPDF setzt einen Exit-Code, der für Build-Skripte und Pipelines die Schalt-Logik liefert. Ein konformes Dokument liefert Exit-Code 0, jede Nicht-Konformität hebt den Code an. Damit klinkt sich die Validierung in jeden gewohnten CI-Mechanismus ein, ohne zusätzliche Parser-Logik.

Validierung in CI-Pipelines integrieren

In der Praxis sieht eine PDF/UA-Validierung in einer CI-Pipeline so aus: Nach dem Build wird das erzeugte PDF gegen veraPDF gefahren. Wenn Befunde auftauchen, bricht der Build ab, und das Team reagiert, bevor das PDF live geht. Das folgende Beispiel zeigt eine GitLab-CI-Konfiguration; für GitHub Actions oder Jenkins ist das Muster identisch.

pdf_ua_check:
  stage: validate
  image: verapdf/verapdf:latest
  script: # 1. Alle gebauten PDFs prüfen 
- verapdf --flavour 
ua1 --recurse 
build/pdf/ --format 
json > report.json # 2. Bericht als Artefakt sichern 
artifacts:
    paths:
      - report.json
    expire_in: 4 weeks
    when: always
  rules:
    - if 
: $CI_COMMIT_BRANCH == "main" 

REST-API für Server-Workflows

Wer veraPDF nicht in jedem Container-Lauf neu starten möchte, betreibt einen Server-Modus. veraPDF bietet dafür eine REST-API über das Projekt veraPDF-rest. Ein PDF wird per POST in den Endpoint /validate gegeben, die Antwort ist eine JSON-Struktur mit den Befunden.

 # Server starten 
java -jar verapdf-rest.jar server config.yml # PDF an REST-Endpoint senden 
curl -X 
POST -H 
 "Content-Type: application/octet-stream" 
\ --data-binary 
@dokument.pdf \ -H 
 "Accept: application/json" 
\
     http://localhost:8080/api/validate/ua1

Befund-Codes lesen und priorisieren

veraPDF meldet Befunde mit einem Rule-ID und einer ISO-Klausel-Referenz. Beispiel: specification: ISO 14289-1, clause: 7.21.3.2, testNumber: 1 . Wer wissen will, was ein Befund bedeutet, kann die Klausel im Standard nachlesen. Praktischer ist der gebündelte Blick:

• Hohe Priorität sind strukturelle Pflichtverletzungen: kein /StructTreeRoot , fehlendes /Lang auf Dokument-Ebene, fehlendes /MarkInfo . Ohne diese gibt es kein PDF/UA.
• Mittlere Priorität sind Tag-Fehler: nicht gemappte Custom-Tags, fehlende /Alt -Attribute auf /Figure -Knoten, falsche Hierarchie der /H<n> -Tags.
• Niedrige Priorität sind Detail-Befunde wie nicht korrekt markierte Artifacts oder Tabula-Spacing-Probleme. Sie müssen für volle Konformität korrigiert werden, blockieren aber selten den ersten Sprint.