Archiving and long-term storage / Validating a PDF/A file
Checking a PDF really is PDF/A before you trust it
Conformance is a property of the bytes, not of the metadata that claims it, and the only way to know which one you have is to run the file through a validator that reports clauses.
Where this API stands
This is not something a renderer emits. It is applied to a finished file by a step that comes after rendering, so the honest answer is about where the boundary falls. Nothing about validation belongs to this API and nothing here can do it: rendering produces a file and checking that file is a separate step in your own pipeline. The one thing the API does tell you is honest and worth reading, which is the warning it returns whenever `pdf_a` is set, stating in the response that the marking is best-effort and that full conformance needs tagged structure and an embedded ICC profile. Treat that warning as the API telling you to validate rather than as boilerplate.
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.
- A validator that names the clause it failed on, so the report is a work list rather than a verdict. veraPDF is the reference implementation and is free and open source.
- The correct flavour, chosen from the part and level you were actually asked for, because a file can pass 2b and fail 1b on the same bytes.
- Validation of the file you ship, after every post-processing step, since anything that rewrites the file can invalidate it.
- A non-zero exit code wired into your pipeline, because a validator whose output nobody reads is a validator that is not running.
- Awareness that validators disagree at the margins. Two implementations can differ on obscure clauses, and the one that matters is the one the receiving system runs.
- Separation of the container check from the content check: PDF/A conformance says nothing about whether the invoice inside adds up.
Who asks for this
You, after the first time a portal rejects a batch of files that opened fine on your machine. Validation is the step that converts an intermittent, unexplained rejection into a specific clause number you can act on, and adding it after the fact usually means reprocessing an archive.
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.
# Reference validator, the flavour you were actually asked for, readable output.
verapdf --flavour 2b --format text statement.pdf
# In a pipeline: fail the build rather than shipping an unchecked file.
verapdf --flavour 2b statement.pdf > report.xml || {
echo "PDF/A validation failed, see report.xml" >&2
exit 1
}
# Run it on the file you actually ship, after signing, merging or stamping.
# Every one of those steps rewrites the document and can invalidate it.What to do about it
Put veraPDF in the pipeline immediately after whatever writes the final file, gate on the exit code, and archive the report next to the document. Run it in a container so the version is pinned, because a validator upgrade that starts enforcing a clause more strictly will otherwise look like a sudden unexplained failure. For a one-off check, the hosted validators and Acrobat preflight are quicker and tell you the same thing.
How to check a file rather than assume
Validate the validator once, deliberately: take a file you know is bad, such as a rendered document with rgba() shadows marked as part 1, and confirm you get the failure you expect on the transparency clause. A validation step that has never failed is indistinguishable from one that is not wired up.
The mistake people make here
Validating before the last step. Signing, encrypting, stamping a page number, merging two documents: every one of those rewrites the file, and any of them can break conformance that was intact a moment earlier. Encryption is the clearest case, because no part of PDF/A permits it, so applying a password after validation produces a file that passed the check and cannot pass it again.
Frequently asked
Does this API produce Validating a PDF/A file?
A step after rendering. Nothing about validation belongs to this API and nothing here can do it: rendering produces a file and checking that file is a separate step in your own pipeline. The one thing the API does tell you is honest and worth reading, which is the warning it returns whenever `pdf_a` is set, stating in the response that the marking is best-effort and that full conformance needs tagged structure and an embedded ICC profile. Treat that warning as the API telling you to validate rather than as boilerplate.
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.
What PDF/A-1b requires, and how far this API gets you
The oldest and strictest archiving profile: a PDF 1.4 file with everything it needs to render sealed inside it, and nothing in it that a future reader might not understand.
PDF/A levels a, b and u, and which one you were asked for
PDF/A on its own is not a specification: it is four parts crossed with up to three conformance levels, and the combination decides whether your job is a converter setting or a month of manual tagging.
Password protection and PDF/A conformance
Why a password-protected file can never be PDF/A or PDF/UA, and what the password option here actually gives you.
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.
PDF/A-2b: what archiving allows once it moves to PDF 1.7
The second part of the archiving standard, rebased on PDF 1.7, which quietly permits most of the things PDF/A-1 banned and is therefore the realistic target for a document produced from a stylesheet.
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.