Metadata, versions and file structure / PDF 2.0
PDF 2.0 and what changed in ISO 32000-2
ISO 32000-2, the first version of PDF published by ISO without an Adobe specification behind it, and the base for PDF/A-4.
Where this API stands
This API does not produce this standard, and there is no option that would. What follows is what the requirement actually is and where a rendered document stands against it. Nothing in this API targets PDF 2.0. There is no version option, and the one conformance option points the other way: `pdf_a` writes a pdfaid packet declaring part 1 and conformance B, which is PDF/A-1b, and PDF/A-1 is defined against PDF 1.4. So `pdf_a` and a PDF 2.0 requirement are pulling in opposite directions, and there is no combination of options here that resolves that. The features 2.0 adds that people usually want, AES-256 and associated files, are both absent from this API entirely.
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 %PDF-2.0 header, or a catalogue /Version raising the file to 2.0.
- The document information dictionary is deprecated: XMP is the metadata mechanism, and /Info survives only for /CreationDate and /ModDate.
- AES-256 encryption is the standard security handler, and the older 40-bit and 128-bit RC4 handlers are removed rather than merely discouraged.
- Unencrypted wrapper documents, page-level output intents, black point compensation and a richer set of annotation and rendering features are all new.
- Associated files, meaning /AF, become a general mechanism rather than something specific to PDF/A-3, which matters for hybrid invoice formats.
Who asks for this
Mostly people who have been told to adopt PDF/A-4, which is defined against PDF 2.0. It also comes up in security reviews, because moving to 2.0 is the clean way to leave RC4 behind, and in e-invoicing, because the associated files mechanism is how a machine-readable payload rides along with the human-readable page.
What to do about it
Convert after the render if you need 2.0, and pick the tool by what you actually need from it. Ghostscript's pdfwrite with -dCompatibilityLevel=2.0 rewrites the file. callas pdfToolbox and Adobe's own tooling will do a 2.0 or PDF/A-4 conversion with a report. If the requirement is really about encryption strength rather than the version, apply AES-256 in that same downstream step and do not use this API's password option, which is 40-bit RC4.
How to check a file rather than assume
The header tells you what the file claims, and veraPDF's PDF/A-4 profile tells you whether a conformance claim holds. For the features rather than the label, `qpdf --json=latest` will show you whether the encryption dictionary is the AES-256 handler or an older one, which is usually the question behind the question.
The mistake people make here
Treating 2.0 as a newer, better version to move to by default. Reader support is good and not universal, some archiving systems still specify PDF/A-2 or PDF/A-3, and relabelling a 1.4-era file as 2.0 changes nothing about what is in it. Move when something you need is only in 2.0, not on principle.
Frequently asked
Does this API produce PDF 2.0?
Not produced by this API. Nothing in this API targets PDF 2.0. There is no version option, and the one conformance option points the other way: `pdf_a` writes a pdfaid packet declaring part 1 and conformance B, which is PDF/A-1b, and PDF/A-1 is defined against PDF 1.4. So `pdf_a` and a PDF 2.0 requirement are pulling in opposite directions, and there is no combination of options here that resolves that. The features 2.0 adds that people usually want, AES-256 and associated files, are both absent from this API entirely.
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.
PDF version numbers and what sets them
The version in the file header and optionally in the catalogue, which says which features a reader must understand to open the file correctly.
PDF/A-4: the conformance letters are gone, what replaced them
The 2020 rebase onto PDF 2.0, which drops the a, b and u conformance letters entirely, makes Unicode mapping mandatory for everyone, and splits the optional extras into two named variants instead.
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.
XMP metadata in a generated PDF
An XML packet in the document catalogue carrying the file's own account of what it is: title, author, dates, and any conformance it claims.
PDF title, author and subject metadata
The older metadata mechanism: a dictionary in the trailer holding /Title, /Author, /Subject, /Keywords and the creation and modification dates.
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.