Metadata, versions and file structure / XMP metadata
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.
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. This is the one place where the API does write metadata, and the scope is exactly one packet under exactly one condition. With `pdf_a` set to true, it writes an XMP stream declaring pdfaid:part 1 and pdfaid:conformance B and sets it as the catalogue's /Metadata entry. That packet contains nothing else: no dc:title, no dc:creator, no xmp:CreateDate, no pdf:Producer. Without `pdf_a`, this API writes no /Metadata entry at all. So if you need descriptive metadata in the file, it is a step you add after the render, and if you need it consistent with the information dictionary, you are setting both in that same step.
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.
- The packet is a stream referenced from the catalogue's /Metadata entry, with /Type /Metadata and /Subtype /XML.
- It is wrapped in xpacket processing instructions and is stored uncompressed and unencrypted, so a tool can find and read it without parsing the whole file.
- Conformance claims live here: pdfaid:part and pdfaid:conformance for PDF/A, pdfuaid:part for PDF/UA, pdfxid:GTS_PDFXVersion for PDF/X.
- Descriptive fields come from standard namespaces: dc:title, dc:creator, dc:description, xmp:CreateDate, xmp:ModifyDate, pdf:Producer.
- PDF/A requires that anything present in both XMP and the information dictionary agrees, and a validator will fail a file where the title differs between the two.
Who asks for this
Document management systems read it on ingest, so it decides how a file is filed and searched. Validators read it to find out what the file claims to be. Anyone auditing a document set reads it to find out what produced a file and when.
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.
<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>
<x:xmpmeta xmlns:x="adobe:ns:meta/">
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about=""
xmlns:pdfaid="http://www.aiim.org/pdfa/ns/id/">
<pdfaid:part>1</pdfaid:part>
<pdfaid:conformance>B</pdfaid:conformance>
</rdf:Description>
</rdf:RDF>
</x:xmpmeta>
<?xpacket end="w"?>
<!-- That is the whole packet written when pdf_a is true. Everything a
document management system would want, dc:title and dc:creator and
xmp:CreateDate, is absent and has to be added downstream. -->What to do about it
Add the descriptive fields downstream with exiftool or a PDF library, in the same pass that sets the information dictionary, so the two cannot disagree. If you are also claiming PDF/A, do the metadata pass before the validation pass, because a mismatch between XMP and /Info is one of the errors a PDF/A validator reports and it is easy to introduce by fixing one and forgetting the other.
How to check a file rather than assume
`exiftool -XMP -b file.pdf` prints the raw packet, which is the quickest way to see what is actually in there. `mutool show file.pdf trailer/Root/Metadata` gets you the stream object. Acrobat shows a subset under document properties, but it merges XMP and /Info in the display, so it is the wrong tool for finding out which one a value came from.
The mistake people make here
Setting the title in the information dictionary and not in XMP, or the other way round. Both are readable, different tools prefer different ones, and PDF/A requires them to agree. A file where /Info says one thing and XMP says another will be described inconsistently depending on which tool opens it, and will fail validation if it claims conformance.
Frequently asked
Does this API produce XMP metadata?
Partly, and the page says how far. This is the one place where the API does write metadata, and the scope is exactly one packet under exactly one condition. With `pdf_a` set to true, it writes an XMP stream declaring pdfaid:part 1 and pdfaid:conformance B and sets it as the catalogue's /Metadata entry. That packet contains nothing else: no dc:title, no dc:creator, no xmp:CreateDate, no pdf:Producer. Without `pdf_a`, this API writes no /Metadata entry at all. So if you need descriptive metadata in the file, it is a step you add after the render, and if you need it consistent with the information dictionary, you are setting both in that same step.
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 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.
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.
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.
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 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.
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.