Archiving and long-term storage / PDF/A conformance levels
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.
Where this API stands
This API does part of what the standard asks for, and the paragraph below is the whole of it rather than a summary of it. The `pdf_a` option commits you to one specific point on this grid and no other: part 1, level B. Those values are written into the XMP packet as literals and there is no parameter to change them. That is fine if 1b is genuinely what you were asked for, and actively harmful if you were asked for 2b, because the file now claims to meet the older and stricter standard and will be judged against transparency rules that would not otherwise apply. Knowing your target pair is what tells you whether to use the option or leave it off and convert.
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.
- Level b means basic: the file will look the same in future as it does now, and nothing more is promised about its content being understandable.
- Level u means level b plus a Unicode mapping for every character, so the text can be extracted, searched and indexed correctly. It exists in parts 2 and 3 only.
- Level a means level u plus a complete logical structure tree, a declared language and alternative descriptions, so the document is machine understandable and accessible.
- Part 4 removes the letters entirely: its baseline includes the Unicode requirement, and the only suffixes left are f for embedded files and e for engineering content.
- The levels are strictly cumulative within a part. There is no level that trades one requirement for another.
- A validator flavour is the pair, not the part: 1b, 2u and 3a are three different targets and a file can pass one and fail another.
Who asks for this
Everybody who has ever received a requirement reading only PDF/A. It arrives in procurement documents, in supplier onboarding checklists and in retention policies, almost always without a part number and usually without a level. Getting the pair pinned down before any engineering starts is the single highest value thing on this page, because the cost difference between 2b and 2a is two orders of magnitude.
What to do about it
Ask two questions before writing any code: which part, and which level. If the answer to the second is a, plan for authoring work rather than a pipeline step, because reading order cannot be generated from a rendered page. If the answer is b or u, this is a conversion problem and a single Ghostscript or preflight step in your pipeline is the whole of it.
How to check a file rather than assume
Run veraPDF at the flavour you were asked for, not the one you assume. If you do not know the flavour, run several: a file that passes 2b and fails 1b is telling you it contains transparency, and a file that passes 1b and fails 2u is telling you the fonts have no Unicode mapping. The pattern of passes is a diagnosis in itself.
The mistake people make here
Reading level a as a stronger version of the same kind of thing as level b. They are different kinds of requirement. Level b is about bytes and can be satisfied by a tool. Level a is about meaning and can only be satisfied by whoever knows what the document says, which is why an automated level a pipeline that nobody reviews produces files that pass validation and fail their purpose.
Frequently asked
Does this API produce PDF/A conformance levels?
Partly, and the page says how far. The `pdf_a` option commits you to one specific point on this grid and no other: part 1, level B. Those values are written into the XMP packet as literals and there is no parameter to change them. That is fine if 1b is genuinely what you were asked for, and actively harmful if you were asked for 2b, because the file now claims to meet the older and stricter standard and will be judged against transparency rules that would not otherwise apply. Knowing your target pair is what tells you whether to use the option or leave it off and convert.
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-2u and the Unicode rule behind broken text extraction
Level b plus one extra rule: every character in the document must map to a Unicode value, so the text can be searched, indexed and copied rather than merely looked at.
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.
PDF/A-3: an archival PDF with a data file inside it
Part 2 with one rule removed: an embedded file no longer has to be a PDF/A file itself, which is what makes a hybrid invoice carrying both a printable page and a machine-readable XML payload possible.
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.