Archiving and long-term storage / PDF/A-3
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.
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. This API has no file attachment support at all: there is no option to embed a file, no Names tree manipulation and no way to set an AFRelationship. A hybrid invoice cannot be produced in one call here. What the API is good for is the half of the problem it does cover, which is turning your invoice markup into the human-readable page that a PDF/A-3 file has to carry, at the right size and with the fields laid out correctly. The attachment is then added by a step that owns the XML.
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.
- Everything part 2 requires for the visible document: fonts embedded, output intent present, no encryption, XMP declaring pdfaid:part 3.
- Embedded files of any format, listed in the catalogue's Names tree under EmbeddedFiles and reachable as file attachment annotations or as associated files.
- An AFRelationship key on each embedded file specification saying what the attachment is to the document: Source, Data, Alternative, Supplement or Unspecified.
- A MIME subtype on the embedded file stream, so a consumer knows what it received without sniffing.
- The visible page must stand alone. The standard does not let the attachment carry meaning that the printed page omits.
- A conformance level of a, b or u exactly as in part 2, so PDF/A-3b and PDF/A-3a are both real things and are not the same requirement.
Who asks for this
Almost entirely e-invoicing. Factur-X and ZUGFeRD are PDF/A-3 files with an EN 16931 compliant XML invoice embedded, and the German and French regimes that use them specify the part and the AFRelationship value explicitly. Outside invoicing it turns up in engineering handover and in regulatory submissions where the reviewer wants the source data alongside the report.
What to do about it
Treat it as two stages with a clear boundary. Generate the XML from your invoice data with a library that validates against the EN 16931 rules, render the human-readable page from the same data so the two cannot disagree, then combine them with a tool that writes PDF/A-3: the Mustang library on the JVM and several PHP and .NET packages do this specifically for Factur-X and set the AFRelationship to Data for you. Validate the XML separately from the PDF, because a file can be perfect PDF/A-3 and carry an invoice that fails every business rule.
How to check a file rather than assume
veraPDF with a 3b or 3a flavour checks the container. It does not check the payload, so pair it with a schema and business rule validation of the extracted XML. For Factur-X specifically the reference validators check the filename, the AFRelationship value and the XMP extension schema as well as the invoice content, and all three are things a hand-rolled attachment step gets wrong.
The mistake people make here
Letting the attachment and the page drift. A PDF/A-3 invoice is one document with two representations, and if the totals block on the page was rendered from a different query than the XML was serialised from, you have shipped a document that contradicts itself in a legally binding way. Generate both from one object in memory, not from two calls to two services.
Frequently asked
Does this API produce PDF/A-3?
Not produced by this API. This API has no file attachment support at all: there is no option to embed a file, no Names tree manipulation and no way to set an AFRelationship. A hybrid invoice cannot be produced in one call here. What the API is good for is the half of the problem it does cover, which is turning your invoice markup into the human-readable page that a PDF/A-3 file has to carry, at the right size and with the fields laid out correctly. The attachment is then added by a step that owns the XML.
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/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-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.
Embedding a file in a PDF/A-3 hybrid invoice
The mechanism behind hybrid invoices: a machine-readable XML payload carried inside an archivable PDF, so one file serves both the person and the system.
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-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.
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.